agentleFS
RedberryProductsRedberryProducts/synapse/.claude/skills/laravel-package/SKILL.md

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
  1. Very specific:

    Config must be cache-safe: No closures in config files (breaks config:cache).

    line 13
  2. Very specific:

    mergeConfigFrom merges only the first level: Don't rely on deep-merging nested config a user partially overrode.

    line 14

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. register() binds; boot() wires. In register(): only mergeConfigFrom and container bindings — never resolve services, hit the DB, or touch facades that need a booted app. In boot(): routes, views, publishing, commands, events, gates, schedules.
  2. Config must be cache-safe. No closures in config files (breaks config:cache). Never call env() at runtime outside a config file — bake env-derived logic into the config's default value and read config() everywhere else. (Synapse's production route-guard does exactly this: 'enabled' => (bool) env('SYNAPSE_ENABLED', env('APP_ENV') !== 'production').)
  3. mergeConfigFrom merges only the first level. Don't rely on deep-merging nested config a user partially overrode.
  4. Guard console-only work. Register commands and publish groups inside if ($this->app->runningInConsole()).
  5. 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.
  6. Package discovery, not manual registration. The provider is auto-loaded via extra.laravel.providers in composer.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):

MethodPurpose
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:publish only warns now); they file_get_contents their compiled dist/ files and inline them into the dashboard. Synapse does the same — nothing lands in the host app's public/, 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 after synapse:install. (publishesMigrations auto-updates the timestamp; Synapse uses fixed timestamps + publishes so the three tables keep a stable order.)

Migrations & models (Synapse conventions)

  • Published migrations are self-contained. Each extends Laravel's Migration and implements getConnection() with config('synapse.storage.connection') ?: config('database.default'); never reference a Synapse class from a published migration because the file remains after composer install --no-dev removes the package.
  • JSON is stored in text columns, not ->json() — sqlite has no native JSON type. Cast to array on 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's HasUuids already yields uuid7 — the HasVersion7Uuids trait does not exist here), $incrementing = false, $keyType = 'string', connection resolved from config. Use const UPDATED_AT = null when a table has only created_at.
  • Always add @property annotations for magic attributes you access (larastan runs with checkModelProperties). Type JSON columns whose element shape isn't guaranteed as array<int, mixed> so runtime is_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 the viewSynapse gate callback. In production, 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's ServiceProvider and guards its Synapse::auth(callback) call with class_exists. The installer registers it locally from AppServiceProvider; Authorize enforces 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, so Synapse::check() isn't "local" — set Synapse::auth(fn () => true) to test authorized access, omit it to test the 403 path.
  • The workbench app (workbench/) holds sample agents for tests and testbench serve. A separate gitignored real Laravel app (testing-laravel-project/, created by bin/setup-testing-app.sh) exercises the true composer require + synapse:install flow.

Frontend (React SPA in a package)

  • Vite builds resources/js → committed dist/ 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 /api prefix; config is injected via window.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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.