Filament Hidden Action Laravel Package

Technical Evaluation

Architecture fit This package is a Filament plugin-style extension for Laravel applications. Its architecture is tightly coupled to Filament's internal contracts — specifically Page::routes() — which is exactly the surface area this release touches. That coupling is normal for the ecosystem but means the package's compatibility envelope is defined by Filament's release cadence, not its own. For a TPM, the practical takeaway is that this dependency should be treated as part of the Filament version line, not as an independent library. Any application standardising on Filament 4.x can adopt it; applications on Filament 3.x are now fully out of scope.

Integration feasibility Installation remains standard Composer work — no new services, no runtime infrastructure, no config migration. Feasibility is high provided the host application is already on filament/filament: ^4.8. The release also adds an explicit filament/actions: ^4.8 constraint to composer.json, which is a positive signal: it makes a previously implicit dependency explicit and reduces the chance of a partial/inconsistent Filament component graph. The blocker is purely version alignment.

Technical risk The headline risk is semver discipline: 1.0.3 is a patch release, yet it contains a breaking change. Any team using ^1.0 with automated dependency updates (Dependabot, Renovate, nightly composer update) can be silently pushed onto a version that refuses to resolve, or worse, resolves alongside a Filament version whose Page::routes() signature no longer matches. Two distinct failure modes:

1. Hard failure (preferable): Composer cannot satisfy filament/filament: ^4.8, install aborts, CI goes red. Visible, cheap, recoverable.
2. Soft failure (dangerous): A lockfile holds an older Filament while an unrelated composer update bumps this package; or an application pins Filament loosely and picks up 4.8 without testing the PageConfiguration argument path. This surfaces as a TypeError / argument-count error at route registration — i.e. at boot, not at build time.

The upstream cause (filamentphp/filament#19225 adding a PageConfiguration parameter to Page::routes()) is a signature change in a framework-internal API. That is a legitimate reason to bump the floor, but it also signals that this package reaches into Filament internals rather than consuming a stable public API. Expect this pattern to recur on every Filament minor that touches routing.

Key questions

• Is there a 1.1.0 (or 2.0.0) planned that re-labels this as a minor/major bump so the breaking change is visible in the version number?
• Does a compatibility shim exist — a 1.0.x line that still supports Filament 4.0–4.7 — or does 1.0.3 orphan everyone below 4.8?
• What is the package's stated Filament support policy (tracks latest minor only, or N-1)?
• Does the package's test matrix actually run against both 4.8 and the current 4.x head?
• Is PageConfiguration consumed directly, or only passed through? Pass-through is a much smaller long-term maintenance burden.
• Is there a published changelog/upgrade guide entry, or only release notes?

Integration Approach

Stack fit Requires Laravel with Filament 4.8+, PHP per Filament 4.8's own floor, and now explicitly filament/actions ^4.8. The package fits cleanly into an existing Filament panel provider registration; no new stack components. Fit is binary — either the host app is on ≥4.8 or this package is unavailable.

Migration path Two upgrade paths, and they must be sequenced in the right order:

• Path A — already on Filament ≥4.8: patch bump only. Run composer update for this package, boot the app, and hit every panel route registered by the plugin. Low effort, low risk.
• Path B — on Filament 4.0–4.7: you must upgrade Filament first, in its own PR, with its own regression pass, then bump this package in a follow-up PR. Combining both into one changeset is the most common way teams lose an afternoon to a boot-time TypeError with an opaque stack trace.

Do not attempt to satisfy the new constraint via composer require --ignore-platform-reqs or by pinning the package to an older tag while bumping Filament. That produces the soft-failure mode described above.

Compatibility Forward-compatible with Filament ^4.8 including future 4.x minors, subject to the internal-API caveat. Backward compatibility with Filament <4.8 is removed, not deprecated — there is no grace period. Applications on Filament 3.x were presumably already unsupported and remain so.

Sequencing

1. Pin/upgrade filament/filament and filament/actions to ^4.8 in the host app; merge and deploy.
2. Bump this package; run a route-registration smoke test (php artisan route:list, then boot each panel).
3. Exercise any custom Page subclasses in the app — those are the most likely to have overridden routes() and to break against the new PageConfiguration parameter.
4. Only then enable automated minor/patch dependency updates for this package.

Operational Impact

Maintenance Ongoing maintenance burden is low but externally driven: every Filament minor that alters an internal API this package touches will force a floor bump here. Budget for a recurring "Filament upgrade → plugin upgrade" chore each Filament minor cycle rather than a one-off. Because the constraint is ^4.8 (not ~4.8.0), you will absorb future 4.x minors automatically — convenient, but it means a future Filament minor could break this package without a version change on either side. Consider whether to pin the host application's Filament to a tested minor.

Support Upstream support surface is the Filament community and the package maintainer. No vendor SLA implied. Internal support cost concentrates in one place: diagnosing boot-time ArgumentCountError/TypeError on Page::routes() after a dependency refresh. Add a runbook entry mapping that error to "version skew between this package and Filament" so on-call doesn't chase it as an application bug.

Scaling No scaling implications — this is a compile-time/registration-time dependency with no runtime footprint, no queues, no storage, no external calls. The only thing that "scales" is the number of panels and custom pages in the app, since each is a potential routes() override site to verify.

Failure modes

• Composer resolution failure on install/CI when Filament < 4.8 is present — loud, safe, blocks the build.
• Boot-time fatal (ArgumentCountError / signature mismatch) when versions are skewed but resolvable — hits every request, effectively full outage; caught by any smoke test, missed by a build-only pipeline.
• Custom Page subclass breakage — narrower blast radius, limited to affected routes; most likely to escape staging if those routes aren't exercised.
• Silent drift via unpinned lockfiles in downstream apps — manifests as inconsistent behaviour across environments rather than a clean error.
• Abandonment risk — a single-maintainer package reaching into framework internals can lag a Filament release; the floor bump is a symptom of actively tracking upstream, which is currently a positive signal.

Ramp-up Negligible for a Laravel/Filament-fluent developer: install, register the plugin in the panel provider, done. The non-obvious knowledge is entirely in the version-skew behaviour — document the Filament floor, the upgrade ordering (Filament before plugin), and the Page::routes() symptom. Half a day of onboarding, most of it spent reading Filament's panel configuration docs rather than this package's.