Filament Hidden Action Laravel Package

Getting Started

Before touching any code, confirm your Filament install meets the new floor:

composer require vendor/package:^1.0.3
composer show filament/filament filament/actions | grep versions

1.0.3 requires filament/actions: ^4.8, so a composer update on a project pinned to Filament 4.6/4.7 will either fail resolution or silently drag Filament forward — check both lock files after install.

Where to look first:

1. The package's config/ file (publish it with php artisan vendor:publish --tag=...) — it tells you which Filament panels/resources the package hooks into.
2. The service provider's boot() / register() — this is where actions and page routes are registered, and it's the fastest way to understand what the package injects.
3. Any shipped Filament Page or Action classes — those are the objects you'll extend or configure.

First use case: register the package's actions on an existing Filament resource table or header, run it against a seeded local database, and confirm the generated routes resolve. That single loop (action → page route → response) exercises the majority of the package's surface.

Implementation Patterns

Panel-scoped registration. Most Filament packages should be wired per-panel rather than globally. Register the plugin/provider inside the specific panel's panel() method so multi-panel apps (admin, tenant, customer) can opt in independently:

->plugin(VendorPackagePlugin::make())

Extending shipped pages. If you override a package page's routes() or getRouteName(), mirror the upstream signature exactly. As of Filament 4.8 (and therefore this release) Page::routes() accepts a PageConfiguration parameter:

public static function routes(PageConfiguration $configuration): array
{
    return parent::routes($configuration);
}

Action configuration over subclassing. Prefer the fluent configuration API (->label(), ->requiresConfirmation(), ->visible()) over subclassing action classes. Subclasses break more often across minor Filament bumps because they capture internal signatures.

Testing. Filament's testing helpers (livewire(), callAction(), assertTableActionExists()) cover the integration points. Test at the page level rather than unit-testing the package's internal classes — the latter are the most likely to shift between releases.

CI matrix. Pin a job to the minimum supported Filament (^4.8) alongside your latest, so the next signature change surfaces in CI rather than in a customer's deploy.

Gotchas and Tips

The 1.0.3 breaking change is transitive. The package itself changed little, but the Filament floor moved to ^4.8. If your app uses composer.json constraints like "filament/filament": "4.7.*", resolution will fail outright. Widen the constraint deliberately rather than deleting the pin.

Overridden routes() methods are the actual breakage. Filament PR #19225 added PageConfiguration as the first parameter to Page::routes(). Any application-level or package-level class overriding that method with the old zero-arg signature will throw a fatal Declaration must be compatible error — usually at boot, not at request time, so a smoke test of php artisan about catches it before anything else.

Clear Filament's caches after upgrading. Route and component caches survive composer update and will serve stale registrations:

php artisan filament:clear-cached-components
php artisan route:clear && php artisan view:clear && php artisan config:clear

Multiple panels multiply the surprise. A plugin registered in one panel but not another produces "action not found" rather than a version error — misleading when you're debugging a Filament bump. Verify each panel's plugin list.

Extension points to prefer. Panel plugins, action configuration closures, and published config are stable across Filament minors. Directly overriding page classes, custom routes() methods, and reaching into Filament internals are the fragile surfaces — treat a Filament minor bump as a prompt to re-audit those specifically.

Debugging resolution failures. composer why-not filament/actions 4.8 names the exact package holding you back, which is far faster than reading the solver output when several Filament-adjacent packages each carry their own floor.