Filament Cms Laravel Package

Getting Started

• Confirm the stack first. filament-cms 2.0.0 targets Laravel 13, Filament 5 and Livewire 4. If your app is still on Laravel 12 / Filament 4 / Livewire 3, stay on the 1.3.x line until you are ready to upgrade the whole admin stack.
• Install the package: composer require webduonederland/filament-cms:^2.0.
• Publish and migrate: publish the package config and migrations using the tags documented in the 2.0 README, then run php artisan migrate. Do this on a fresh branch or local environment before touching production.
• Register the CMS plugin in your Filament panel provider. The usual pattern is ->plugin(FilamentCmsPlugin::make()); confirm the exact class and namespace in the package README because Filament 5 plugin registration should be treated as the source of truth.
• Read UPGRADE.md before installing. The 2.0.0 release explicitly calls out breaking changes and points to UPGRADE.md. Even for a fresh install, that file tells you which config keys, views, routes or resource customisations changed.
• First use case: open the CMS resources in the Filament admin, create a page, attach one of the provided blocks, save it, then visit the front-end route generated for that page. This validates installation, routing, storage and rendering in one pass.
• Where to look first: the package README for installation/publish tags, UPGRADE.md for 2.0 changes, the package config file for route prefix/middleware/disk settings, and the package source for the Page model, block classes and route registration.

Implementation Patterns

• Model content as pages plus blocks. Use the package’s page types/templates and block system rather than adding ad-hoc columns to your own models. Day-to-day editing then stays inside Filament, and front-end rendering stays consistent.
• Create custom blocks for reusable content. A typical custom block has three parts: a block class/definition, a Filament form schema for editor input, and a Blade view for output. Register custom blocks through the package’s documented extension point, not by editing vendor files.
• Render through the package’s page resolution where possible. Let the CMS own slug resolution, page status and route registration. If you need custom controllers, resolve the package Page model and reuse its block-rendering API so previews and live pages behave the same.
• Cache rendered pages aggressively. CMS pages are read-heavy and change infrequently. Cache rendered HTML or block output keyed by page ID and updated_at, and invalidate in a model observer or save hook. This is usually the biggest day-to-day performance win.
• Separate editorial and application concerns. Keep CMS pages for marketing/content pages and normal Laravel controllers for account, checkout, dashboard and other dynamic flows. Use the CMS for what it is good at rather than forcing every route through it.
• Use policies and panel access control. Restrict CMS resources to editor/admin roles via Filament policies or panel canAccess() checks. Content tools should not be exposed to every authenticated user by default.
• Build an upgrade workflow. For 2.0.0: create a branch, run composer update with the new constraints, follow UPGRADE.md step by step, republish changed assets/views, run migrations, then exercise page creation, block editing, front-end rendering and media uploads before merging.
• Keep customisations in app code. Prefer package config, custom block registration, published views and your own wrapper classes over patching vendor files. That keeps future major upgrades tractable.
• Add smoke tests around CMS routes. A small feature test that creates a page with a block and asserts the front-end response contains expected content will catch most upgrade regressions.

Gotchas and Tips

• 2.0.0 is a breaking release. Do not treat it as a routine composer update. Follow UPGRADE.md in full; skipping steps is the most likely way to end up with broken admin pages, missing routes or stale published assets.
• Filament 5 is the main compatibility risk. Custom Filament resources, forms, tables, actions and block schemas that extend or mimic package classes may need signature and API updates. Check any custom block/resource code against the Filament 5 upgrade guide.
• Livewire 4 affects custom admin components. If you have custom Livewire components inside the CMS panel, test lifecycle hooks, component registration and wire: bindings. The package upgrade does not automatically upgrade your custom components.
• Dependency conflicts are likely in larger apps. Use composer why-not webduonederland/filament-cms 2.0.0 and composer why-not filament/filament ^5.0 to find packages still pinning Filament 4 or Livewire 3. Upgrade the whole panel stack together.
• Republishing can overwrite local changes. If you previously published and customised package views/config, back them up or diff before running vendor:publish --force. Keep published customisations under version control.
• Clear caches after upgrading. Run php artisan optimize:clear, then re-run filament:optimize / filament:cache-components if your deployment uses Filament optimisation. Stale cached components after a major Filament upgrade can look like package bugs.
• Check route registration explicitly. Use php artisan route:list and filter for the CMS route prefix. If pages 404 after upgrade, the issue is often a changed config key, middleware group or route prefix rather than missing content.
• Verify storage and media configuration. Check the configured disk, upload rules and image conversion settings in the published config. A stack upgrade can change defaults or reveal missing storage links (php artisan storage:link).
• Debug rendering at the block level. If a page renders but a section is blank, isolate the block: confirm the block is registered, the Blade view exists, and the block data shape matches what the view expects. This is faster than debugging the whole page response.
• Extension points to prefer. Custom block registration, page model resolution, route middleware/config overrides, published Blade views and model observers are safer long-term than subclassing deep internals. Re-check those extension points against UPGRADE.md before every major release.
• Pin constraints in production. Use ^2.0 rather than *, commit composer.lock, and test the upgrade in CI with the same PHP, Laravel 13, Filament 5 and Livewire 4 versions you run in production.