laravel-package
Skill65 starsChanged 19 days agoMITView on GitHub
Best practices for developing the Synapse Laravel package (and Laravel packages in general) — service provider register/boot split, publishing config/migrations/assets, package discovery, Testbench + Pest testing, config-cache safety, and Synapse's own conventions. Use when adding or modifying package plumbing: service providers, config, routes, migrations, models, commands, publishing, or tests.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 0 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Config must be cache-safe: No closures in config files (breaks config:cache).
- Very specific: line 14
mergeConfigFrommerges only the first level: Don't rely on deep-merging nested config a user partially overrode.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Laravel Package Development (Synapse)
Distilled from the Laravel 13 package docs, laravelpackage.com, and Synapse's implementation. When these conflict with the repo's existing patterns, follow the repo — the conventions below already match it.
Golden rules
register()binds;boot()wires. Inregister(): onlymergeConfigFromand container bindings — never resolve services, hit the DB, or touch facades that need a booted app. Inboot(): routes, views, publishing, commands, events, gates, schedules.- Config must be cache-safe. No closures in config files (breaks
config:cache). Never callenv()at runtime outside a config file — bake env-derived logic into the config's default value and readconfig()everywhere else. (Synapse's production route-guard does exactly this:'enabled' => (bool) env('SYNAPSE_ENABLED', env('APP_ENV') !== 'production').) mergeConfigFrommerges only the first level. Don't rely on deep-merging nested config a user partially overrode.- Guard console-only work. Register commands and publish groups inside
if ($this->app->runningInConsole()). - Publish host-owned resources with separate tags. Config, migrations, and the application provider are publishable. Compiled dashboard assets stay inside the package and are never published.
- Package discovery, not manual registration. The provider is auto-loaded via
extra.laravel.providersincomposer.json.
Service provider anatomy
public function register(): void
{
$this->mergeConfigFrom(__DIR__.'/../config/synapse.php', 'synapse');
// container bindings only
}
public function boot(): void
{
$this->registerRoutes(); // guarded by config
$this->loadViewsFrom(__DIR__.'/../resources/views', 'synapse');
$this->registerScheduledTasks(); // conditional
if ($this->app->runningInConsole()) {
$this->registerPublishing(); // tagged groups
$this->registerCommands();
}
}Service-provider methods (lifecycle noted below):
| Method | Purpose |
mergeConfigFrom($path, $key) | Provide config defaults (in register) |
loadViewsFrom($path, 'synapse') | Register views as synapse::view; user override via resources/views/vendor/synapse |
loadRoutesFrom($path) | Load routes; auto-skips when routes are cached |
loadMigrationsFrom($path) | Auto-run migrations (Synapse does not use this — see below) |
commands([...]) | Register Artisan commands |
AboutCommand::add(...) | Add a row to php artisan about |
Publishing (tagged groups)
$this->publishes([__DIR__.'/../config/synapse.php' => config_path('synapse.php')], 'synapse-config');
$this->publishes([__DIR__.'/../database/migrations' => database_path('migrations')], 'synapse-migrations');
$this->publishes([__DIR__.'/../stubs/SynapseServiceProvider.stub' => app_path('Providers/SynapseServiceProvider.php')], 'synapse-provider');- Users publish a group with
php artisan vendor:publish --tag=synapse-config, or everything with--provider="Redberry\Synapse\SynapseServiceProvider". - Assets are not published at all. Current Horizon and Telescope both stopped publishing them (
horizon:publishonly warns now); theyfile_get_contentstheir compileddist/files and inline them into the dashboard. Synapse does the same — nothing lands in the host app'spublic/, so an upgrade can never leave stale assets behind and there is no re-publish step. - Migrations: Synapse publishes them (Telescope-style), it does not
loadMigrationsFrom. They run when the app migrates aftersynapse:install. (publishesMigrationsauto-updates the timestamp; Synapse uses fixed timestamps +publishesso the three tables keep a stable order.)
Migrations & models (Synapse conventions)
- Published migrations are self-contained. Each extends Laravel's
Migrationand implementsgetConnection()withconfig('synapse.storage.connection') ?: config('database.default'); never reference a Synapse class from a published migration because the file remains aftercomposer install --no-devremoves the package. - JSON is stored in
textcolumns, not->json()— sqlite has no native JSON type. Cast toarrayon the model. - No DB foreign keys for cascade. sqlite's FK pragma is off by default; cascade deletes live in
ConversationRepository, not the schema. - Models extend
Redberry\Synapse\Models\SynapseModel:HasUuids(this framework'sHasUuidsalready yields uuid7 — theHasVersion7Uuidstrait does not exist here),$incrementing = false,$keyType = 'string', connection resolved from config. Useconst UPDATED_AT = nullwhen a table has onlycreated_at. - Always add
@propertyannotations for magic attributes you access (larastan runs withcheckModelProperties). Type JSON columns whose element shape isn't guaranteed asarray<int, mixed>so runtimeis_array()guards remain valid.
Authorization (dashboard packages)
Telescope/Horizon pattern, used by Synapse:
- Open in
local; denied by default elsewhere. Explicitly registering the published application provider installs theviewSynapsegate callback. Inproduction, routes do not register unless explicitly enabled. - The gate lives in a published application service provider stub (
stubs/SynapseServiceProvider.stub→app/Providers) so users own it. The published stub extends Laravel'sServiceProviderand guards itsSynapse::auth(callback)call withclass_exists. The installer registers it locally fromAppServiceProvider;Authorizeenforces access.
Testing (Orchestra Testbench + Pest)
// tests/TestCase.php
abstract class TestCase extends \Orchestra\Testbench\TestCase
{
protected function getPackageProviders($app): array { return [SynapseServiceProvider::class]; }
protected function defineDatabaseMigrations(): void
{
$this->loadMigrationsFrom(dirname(__DIR__).'/database/migrations');
}
protected function defineEnvironment($app): void
{
$app['config']->set('database.default', 'testing');
$app['config']->set('database.connections.testing', ['driver' => 'sqlite', 'database' => ':memory:', 'prefix' => '']);
}
}// tests/Pest.php
uses(TestCase::class, RefreshDatabase::class)->in('Feature', 'Unit');
uses(BrowserTestCase::class, RefreshDatabase::class)->group('e2e')->in('Browser');Browser e2e in a package. Pest 4's browser plugin boots the Testbench app in-process (no artisan serve). Because Synapse inlines its assets from dist/, nothing needs copying into the Testbench public dir — BrowserTestCase just opens the auth gate and skips (not fails) when dist/ isn't built. Suites are split in phpunit.xml.dist (unit, feature, e2e) so composer test stays fast and composer test:e2e is opt-in.
- Migrations are publish-only in production but loaded explicitly in tests via
defineDatabaseMigrations()(they never auto-register in the app). - Env in tests is
testing, soSynapse::check()isn't "local" — setSynapse::auth(fn () => true)to test authorized access, omit it to test the 403 path. - The workbench app (
workbench/) holds sample agents for tests andtestbench serve. A separate gitignored real Laravel app (testing-laravel-project/, created bybin/setup-testing-app.sh) exercises the truecomposer require+synapse:installflow.
Frontend (React SPA in a package)
- Vite builds
resources/js→ committeddist/with stable filenames (app.js,app.css). Users never run npm. Synapse::css()/js()read those files off disk and inline them as<style>/<script type="module">(returns an HTML comment when unbuilt — never fatal). No manifest, no hashing, no publishing.- One blade shell + a catch-all route (
/{view?}where(.*)); the JSON API lives under a/apiprefix; config is injected viawindow.Synapse = @json(Synapse::scriptVariables()). - Stack: React + TypeScript, Tailwind v4 (CSS-first
@theme, no config file), local UI primitives, and path alias@/ → resources/js. Synapse owns its SSE reader; it does not depend on the Vercel AI client.
SDK dependency note
laravel/ai resolves from Packagist using composer.json constraints. Do not wire references/laravel/ai as a canonical path repository for installation QA: that would test a local SDK checkout instead of the published dependency. See DEV.md.
For SDK 1.3, persist Responses\Data\Step::toArray() in Synapse's private history and project display data separately. SDK execution IDs and model tool-call IDs are distinct. Register event listeners once, activate recording only during the playground invocation, and restore scope in finally; never remove a host application's listeners. Forward agent middleware, skills, and cache settings through the decorator. Discovery must merge skill tools with LoadSkill::mergeInto() and recognize SDK-wrapped sub-agent/MCP tools.
Storage changes use self-contained follow-up migrations. Prefer additive migrations that preserve history. The legacy 0.1.x → 0.2.0 migration required an explicit clear using the old installation; do not apply that reset to ordinary upgrades. Verify the configured connection and package-absent migration loading. See the upgrade guide.
Qualify Laravel 12 and 13 on real PHP 8.3 and 8.4 runtimes, including the exact SDK floor and latest stable allowed resolution. Keep dependency experiments in isolated copies; do not overwrite the developer's lockfile or preview app. Run feature and browser suites sequentially within each copy: installation tests temporarily publish/remove Testbench migrations. GD is required by upload test fixtures. Verify HTTP flushing separately with a slow deterministic tool and output buffering enabled; CLI tests cannot prove streaming.
See also
- AGENTS.md — Synapse architecture map + coding standards.
- DEV.md — exact dev-cycle commands (test / lint / analyse / build).
- README.md and UPGRADE.md — supported behavior and version-specific migration instructions.
- The active GitHub issue and user request — goal, scope, and acceptance criteria; merged PRs retain completed implementation history.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

