Filament Headless Cms Laravel Package

Getting Started

• Install the package with Composer alongside Filament (v3+ assumed) — composer require phpsa/filament-headless-cms. Confirm the Filament version constraint in composer.json before you commit; headless CMS packages tend to pin tightly to Filament majors.
• Publish and run the assets — php artisan vendor:publish --provider="Phpsa\FilamentHeadlessCms\...ServiceProvider" (check php artisan vendor:publish output for the exact tags), then php artisan migrate. Review the published config file before migrating, since table prefixes and content-type drivers are usually baked into migrations.
• Register the plugin on a panel in your PanelProvider (->plugin(...)) — this is the standard Filament entry point and is where you'll add the CMS resources to an existing admin panel rather than standing up a second one.
• Look here first, in order: the package README, the published config/*.php, the service provider's register()/boot() (to see what routes, policies, and Livewire components get bound), then the src/Models directory. The models tell you more about the data shape than the docs will.
• First use case: stand up a Page/content-type resource in the admin, author one entry, then hit the exposed JSON endpoint (or your own Route::get wrapping the package's query scope) from curl. Getting one document out end-to-end on day one surfaces 90% of the config issues.

Implementation Patterns

• Admin-first authoring, API-second delivery. Use the Filament panel as the editorial surface and treat the package's models as the read model for your front end (Next/Nuxt/Inertia/mobile). Keep your consumer code behind a thin repository or API Resource layer so a future package upgrade doesn't ripple into your front end.
• Eloquent-first integration. The package's content models are almost certainly standard Eloquent models, so relationships, scopes, global scopes, and API Resources all work normally. Prefer extending or composing over the shipped models rather than forking package files.
• Seeding and fixtures. Seed content types and sample entries in DatabaseSeeder so local and CI environments are reproducible — a CMS package with an admin UI tempts teams into hand-authoring content that never makes it into tests.
• Authorization. Wire the package's policies into your existing role model (Spatie Permission / Filament Shield) rather than granting broad panel access. Editorial roles (author vs. publisher) are the usual gap once real users arrive.
• API surface ownership. If the package ships routes, put them behind your own route group/middleware (throttling, Sanctum, CORS) in RouteServiceProvider or the panel provider. If it doesn't, expose content via API Resources — that keeps versioning (/api/v1/...) under your control.
• Caching. Published content is read-heavy and write-light: cache rendered responses or query results keyed by entry ID + updated_at, and bust on the package's save/publish events (Model::saved, or a dedicated event if one is dispatched). Filament observers are a clean place to hang this.
• Preview workflow. Use draft/unpublished states to serve a preview token route for editors, separate from the public cached route. This is the single most-requested feature from content teams and usually cheap to add on top of the package's status column.

Gotchas and Tips

• Read the diff, not the notes. v1.1.0's release body is only a link to the v1.0.1...v1.1.0 comparison. A minor bump on a young package often carries schema changes, renamed config keys, or Filament component moves — open the compare view and scan database/migrations, config/, and any renamed classes before upgrading.
• Published config drifts. Once you publish config/filament-headless-cms.php, new config keys added in a release silently fall back to package defaults. Diff your published copy against the package's config/ on every upgrade.
• Migration ordering. Vendor migrations often run under their own timestamp; if you published them into database/migrations, they can end up ordered before the users table and break foreign keys on a fresh install. Prefer running vendor migrations from the package (vendor:publish only the config) unless you need to edit them.
• Storage disks and URLs. Uploads typically resolve through config('filesystems.disks.public'); a missing storage:link or an S3 disk without the right visibility produces broken media URLs that look like a package bug.
• Cache invalidation on publish. Cache the public read path aggressively but always clear on save/unpublish. Editors who "publish and don't see it" will file bugs against the CMS, not the cache.
• Extension points to prefer: model $fillable/$casts overrides via subclass + container binding, Filament resource extension (Resource::getPages(), form/table schema modifiers), and events/observers — these survive minor upgrades far better than editing vendor views.
• Debugging a missing field or endpoint: php artisan route:list --path=<prefix>, then php artisan about to confirm the panel plugin actually registered. Most "it's not working" reports trace back to the plugin never being added to a panel the user has access to.
• Pin the version in composer.json ("phpsa/filament-headless-cms": "^1.1") and let Dependabot surface future releases with proper notes, given how terse this one was.