Filament Simple Permissions Laravel Package

Technical Evaluation

Architecture fit: z3d0x/filament-simple-permissions is a thin Filament plugin: a RoleResource (and accompanying pages/actions) layered over spatie/laravel-permission for storage and check semantics. That is the right shape for the problem — Filament panels need a UI to manage roles, and spatie/laravel-permission is the de facto standard for the underlying model. The package deliberately does not invent an ACL engine, which is a genuine architectural positive: the blast radius of the dependency is a set of Filament screens and a config file, not a bespoke permission schema. The correct TPM framing is that this package is not a platform decision — it is a small, replaceable UI layer over a dependency we would likely standardize on anyway.

Integration feasibility: High on technical merit. Composer install, config publish, one plugin registration in PanelProvider::panel(), then spatie migrations. No service provider overrides, no queue workers, no external services, no data migration beyond spatie's own tables. An engineer can have it running in a non-production panel in under a day. The feasibility question is therefore not "can we integrate it" but "can we keep it integrated," which is answered by the archival status below.

Technical risk: The dominant risk is upstream abandonment, and it has already materialized. The repository is archived and the last release was 2023-06-09. Archival is categorically different from "low activity": it means no security patches, no Filament major-version compatibility work, no issue triage, and no disclosure channel. Because Filament ships majors on a roughly annual cadence, this package is already — or will imminently be — a hard blocker on panel upgrades. Secondary risks:

• Security surface with outsized blast radius. The package gates admin-panel access. A silent misconfiguration (guard mismatch, a Gate::before super-admin bypass that is broader than intended, stale permission cache) results in over- or under-privileged admins. This is the class of bug that shows up in an audit, not in CI.
• Transitive health is inverted from the usual pattern. The risky component (this plugin) is dead; the valuable component (spatie/laravel-permission) is healthy and actively maintained. That asymmetry matters — it means the migration path out of this package is cheap, because the hard part (data model, seeding, caching) lives in spatie and survives.
• Signal quality. 11 stars and a final release consisting entirely of Dependabot bumps to a CI action is not a maturity signal in either direction; it tells us nobody is watching. Do not read the archived state as "stable and finished" — it is "stopped."

Key questions:

• Which Filament major version does the archived code target, and which majors does our roadmap require over the next 12–18 months? This single answer likely decides the build-vs-adopt call.
• Does the plugin's config and spatie config agree on guard names today, and who owns that decision permanently?
• Are we willing to fork and own ~a few hundred lines under our own namespace, with a named maintainer and a test suite? If not, we should not adopt at all.
• What does the package do that a hand-rolled RoleResource over spatie (roughly a day of work) does not?
• Do we have any compliance or security-review obligation that a vendor-archived, unmaintained package cannot satisfy?

Integration Approach

Stack fit: Laravel + PHP + Filament, with spatie/laravel-permission as a hard prerequisite (install it and run its migrations first; the plugin assumes its tables and cache). No infrastructure implications — no new services, no queue, no storage, no runtime footprint beyond the request cycle. Confirm PHP/Laravel/Filament constraints from composer.json before committing, since the archive means those constraints are frozen at the 2023 state and may already exclude our current Filament.

Migration path: There are three realistic starting points, and they deserve different answers:

• No existing ACL: Do not adopt this package. Install spatie/laravel-permission directly (it is maintained, documented, and has its own Filament ecosystem support) and build or vendor the role-management screen ourselves. The plugin saves perhaps a day and costs us a permanent compatibility liability on the panel upgrade path — a bad trade at this size.
• Already on spatie with no UI: Same conclusion. The missing piece is a role screen, and a role screen is the cheapest possible thing to own. Keep spatie as the system of record; treat the UI as disposable.
• Already running this package (brownfield): Do not rip it out mid-quarter. Fork it into our namespace, pin the dependency, add a Filament-version compatibility test, and schedule replacement at the next Filament major upgrade. Because all state lives in spatie tables, this is a UI swap, not a data migration — the exit cost is low, which is exactly why deferring is defensible.

Compatibility: The binding constraint is the Filament major version, not Laravel or PHP. Determine it by spike, not by changelog — the archive contains no compatibility statement worth trusting. Assume no Filament 4+ support until proven otherwise, and plan for the possibility that the answer is "already incompatible."

Sequencing:

1. Spike first, decide second. Stand the plugin up on a throwaway panel against our current Filament version. If it does not install cleanly, the decision is made for us.
2. Settle the storage and guard question before any UI work. spatie as system of record, one guard, permissions defined as data in a seeder. This is the expensive-to-reverse decision; the UI is not.
3. If adopting (brownfield only): fork and own. Vendor the code under app/Filament or an internal package, pin the version, and add a test that fails loudly on the next Filament bump.
4. If greenfield: build the thin screen. Scope it as a single Filament resource plus policies, with permission definitions in a seeder and enforcement in Gate/policies — never in the UI layer.
5. Deploy-path integration: idempotent permission seeder, permission:cache-reset and config:cache ordering baked into the pipeline, not left to runbooks.
6. Only then assign a named owner and add the Filament-upgrade check to the recurring maintenance calendar.

Operational Impact

Maintenance: The upstream maintenance cost is zero because upstream maintenance has ended — which converts directly into our cost. Budget for: re-validating Filament compatibility on every major, carrying a fork through security reviews, and tracking spatie upgrades against a plugin that will not be updated to match. A forked, pinned, single-screen package of this size is genuinely cheap to own (low single-digit engineer-days per year), but it must be owned, not merely installed.

Support: None. No vendor, no SLA, no security disclosure path, no maintainer to escalate to. The practical escalation route is reading our own fork. That is acceptable for internal admin tooling where the users are our own staff; it is not acceptable for anything customer-facing, regulated, or covered by a security questionnaire that asks how we patch admin-access dependencies.

Scaling: No scaling risk inherent to the package — it is a small CRUD screen plus spatie's cached permission lookups. The two things to test rather than assume: (a) cache behavior under multiple app servers and deploy-time cache warmers, where a stale permission map produces inconsistent authorization across nodes; and (b) the role screen's query cost if role and permission counts grow into the hundreds, which is unusual but worth eyeballing. Neither is a reason to reject; both are testable in the spike.

Failure modes, ranked by likelihood and pain:

1. Upgrade blockage (high likelihood, high pain). Filament ships a major; the plugin cannot follow; every panel upgrade becomes a fork-patch. This is the failure we should design against from day one.
2. Silent authorization drift (medium likelihood, severe pain). Guard mismatch between the panel and spatie config, a permission deleted while still referenced by a policy, or a Gate::before super-admin bypass that is broader than intended. All of these fail open on the admin UI and closed in production, or vice versa — and none throw an exception.
3. Stale permission cache (medium likelihood, low pain, high confusion). A freshly granted permission that "doesn't work" after a deploy. Mitigated by putting the cache reset in the pipeline rather than in a wiki page.
4. Seeder/UI divergence (medium likelihood, medium pain). Permissions created by hand in the UI that no seeder knows about, and vice versa. Fix by making the seeder authoritative and the UI a consumer.
5. Bus factor on the fork (low likelihood, medium pain). A one-screen package nobody remembers owning is exactly the thing that gets orphaned twice.

Mitigations are cheap and should be treated as adoption prerequisites, not follow-ups: an integration test asserting deny-by-default per panel page, an explicit test that a non-super-admin is still blocked, one guard decision documented in the ADR, and the permission seeder wired into the deploy.

Ramp-up: Developer ramp-up is minimal — half a day to a day for a Laravel-fluent engineer, most of which is spent understanding Filament's authorization conventions and the guard config rather than this package. The real ramp-up is organizational and recurring: someone must own the fork, the Filament-compatibility question, and the decision to eventually replace the UI. Assign that owner before adoption. If no one will take it, that is the answer — don't adopt.

Recommendation: Treat this package as a reference implementation, not a dependency. The archived status converts a one-day convenience into an indefinite compatibility liability on the most-upgraded layer of the stack, for a component that is a small spatie-backed Filament resource. Standardize on spatie/laravel-permission as the system of record, own the ~one-screen role UI, and keep the permission model in seeders and enforcement in policies. Where the plugin is already deployed, pin and fork it, and schedule its replacement alongside the next Filament major — the exit cost is low precisely because all durable state lives outside it.