Filament Security Headers Laravel Package

Getting Started

This release (3.0.0) is a compatibility cut, not a feature cut: the headline is "First release for Filament 5.x." That single line drives almost everything about how you adopt it.

1. Check your Filament version first. Run composer show filament/filament. If you are still on Filament 3.x or 4.x, do not take this update — pin to the last 2.x release and treat ^3.0 as blocked until your panel is upgraded.
2. Upgrade the host app before the package. Move Filament to 5.x, resolve its own upgrade guide items, get the panel booting, then composer require the new major.
3. Republish assets and config. A new Filament major almost always means new compiled CSS/JS expectations. Expect to re-run php artisan vendor:publish --tag=...-assets --force (or rebuild your panel theme) and diff the published config against the previous version.
4. Register the plugin in your PanelProvider exactly as before — the public registration API is typically the most stable surface across a major bump, so ->plugin(MyPlugin::make()) should be your sanity check that the wiring still works.

Where to look first: the package's UPGRADING.md / changelog for the 2.x → 3.x delta (the release note is one line, so the real detail lives there), then the plugin class itself, then the composer.json constraints to confirm the exact Filament floor (^5.0 vs ^5.1).

First use case: boot a single panel with the plugin registered, load the page/resource it provides, and confirm the rendered output matches what you had on the previous major. That one smoke test catches the majority of Filament-major breakage.

Implementation Patterns

Treat 3.0.0 as a hard version gate, not a soft one. Because the package now targets Filament 5.x, the dominant day-to-day pattern is coordinated upgrades: Filament major and package major move together in the same PR, with the package constraint bumped in lockstep. Avoid patterns where the package version floats independently of the Filament version.

Multi-panel setups. If you run several panels (admin, tenant, customer), register the plugin per-panel and verify that any Filament-5-era registration changes (navigation grouping, panel-scoped config) still resolve correctly in each. A package that works in one panel can silently fail to register in another when the plugin reads panel context.

Fluent/plugin configuration. Most Filament plugins expose ::make()->someOption() builders. Keep these in dedicated config or a small helper rather than inlining them in the provider — it makes the next major bump a one-file change instead of a grep exercise.

Resource and form/table integration. Where the package ships form components, table columns, or actions, prefer the package's published components over hand-rolled equivalents. On a major bump, custom forks of package internals are the #1 source of upgrade pain; anything you copied out of the package's src/ is now your maintenance burden against a new Filament API.

Testing. Filament's Livewire test helpers (livewire(...)->assertSuccessful(), assertCanSeeTableRecords, callAction) plus Pest/PHPUnit are the cheapest way to prove the upgrade landed. Write one test per surface the plugin touches — a page renders, a table column resolves, an action fires — before and after the bump. This is worth doing before upgrading, because it gives you a red/green signal you otherwise won't have.

Asset and theme workflow. If you compile your own panel theme, the Tailwind/Vite pipeline must be rebuilt after upgrading; package-provided views may now reference new Filament classes. Bake npm run build and asset publish into the upgrade runbook.

Gotchas and Tips

• Do not mix majors across a monorepo. A single package on ^3.0 (Filament 5) alongside a sibling still pinned to Filament 4 will deadlock Composer. Upgrade the whole workspace or use path repositories carefully.
• The release note is one line — that is the pitfall. "First release for Filament 5.x" tells you nothing about behavioural changes. Read the diff between the last 2.x tag and 3.0.0, and read Filament 5's own upgrade guide. Assume deprecations exist until proven otherwise.
• Clear every cache. Filament caches components and Blade views aggressively. After the upgrade: php artisan filament:clear-cached-components (or optimize:clear), view:clear, config:clear, and composer dump-autoload. A large share of "the upgrade broke everything" reports are stale caches.
• Watch navigation and icon rendering. Small API shifts in navigation registration and icon resolution are common across majors and show up as missing menu items rather than exceptions — easy to miss in a quick visual check.
• Check published config drift. If you published config in 2.x, the 3.0 config file may have new keys with defaults you now don't have. Diff published configs; missing keys silently fall back and can change behaviour.
• Extension points beat forks. When something needs tweaking, prefer the plugin's documented hooks, macros, view overrides, or configureUsing() over editing vendor code — vendor edits vanish on the next composer update.
• Pin the minor while it's fresh. "^3.0" is fine, but in the first weeks of a new major consider a tighter constraint so a 3.0.x patch doesn't land mid-deploy without review.
• Have a rollback. Since this is a major with a new-host-major requirement, keep the lockfile diff isolated in its own commit so reverting is a git revert rather than archaeology.