bezhansalleh/filament-shield
Shield adds complete access management to Filament panels: resource, page, and widget permissions, custom permissions, and automatic policy generation, with per-resource policies and seamless role integration.
Architecture fit. Shield is a thin orchestration layer over spatie/laravel-permission, which is the de facto authorization primitive in the Laravel ecosystem. Architecturally it does three things: (1) emits permission keys and policies derived from Filament's discovered Resources/Pages/Widgets, (2) ships an admin UI/plugin for role→permission assignment, and (3) intercepts authorization via a super-admin Gate::before and generated policies. That is a good fit for us because the runtime dependency is a mature package we would likely adopt anyway; Shield is largely build-time tooling plus an optional admin panel. The risk concentration is not in the authorization engine but in the code-generation contract it imposes on our permission naming and policy files.
Integration feasibility. Low friction on paper: composer require, publish config, set auth_provider_model, add HasRoles to User, run interactive shield:setup. Constraint is tight coupling to Filament's major version: the 4.x line targets Filament 4.x and 5.x, and prior lines were separate rewrites (2.x→3.x→4.x). Feasibility therefore reduces to a single gating question — do we control our Filament major, and can we accept upgrading this package in lockstep with it?
Technical risk.
case + separator + subject determine the strings persisted in permissions, role_has_permissions, and model_has_permissions. Changing them post-production requires a data migration. The config also throws InvalidArgumentException on incompatible separator/case pairs (e.g. _ with snake) — an easy boot-time failure from a copy-pasted config.buildPermissionKeyUsing callback. This is the single most likely source of silent privilege bleed in a large panel.enabled flag left on is a full authorization bypass, not a degraded mode.app/Models → mirrored Policies; vendor models → flat; module/DDD Models dirs → sibling Policies; legacy → flat). Only one of those rows is reliably found by Laravel's discovery without registration — assume manual Gate::policy wiring for module layouts.Key questions. Which Filament majors and how many panels do we run? Is spatie/laravel-permission already live (with existing roles to migrate) or greenfield? Do we use spatie teams / Filament multi-tenancy? Are policies generated-and-committed or hand-authored with Shield skipped? Do we need externally managed permissions (Keycloak/Okta-style, handled by returning null from the key builder)? What is our definition of super admin, and is it auditable?
Stack fit. The dependency chain is Filament → Shield → spatie/laravel-permission. Confirm the lockfile resolves Shield 4.x against our Filament constraint before any design work; if we are on Filament 3.x, Shield 3.x is the only supported pairing and should be treated as a separate, older codebase with a known migration cliff ahead of it. On a greenfield panel the fit is clean and we should adopt it. On a panel with hand-rolled is_admin flags or custom gates, plan to reconcile, not replace, semantics.
Migration path. Order of work: (1) inventory Resources/Pages/Widgets and all existing authorization mechanisms, producing a role × resource × action matrix as the target state; (2) decide and freeze the permission key convention — an ADR covering case, separator, subject, and the collision callback for namespaced duplicates; (3) run shield:generate in a scratch branch and review the emitted permission catalogue and policies as code, not as output; (4) diff generated policies against any existing hand-written ones and decide per-model whether merge is safe or the policy should be skipped; (5) seed roles via shield:seeder in staging; (6) cut over in production with the super-admin gate enabled first and role grants phased.
Compatibility. Two axes. Upward: Shield 4.x covers Filament 4.x and 5.x, so a Filament 5 upgrade stays within the support window — but it is still a coordinated bump, not a silent one. Downward: any pre-existing Shield 3.x install cannot be upgraded in place; budget a dedicated migration ticket. Internally, HasRoles on the auth provider and the correct auth_provider_model in config are hard prerequisites — get them wrong and authorization fails open or throws, depending on path.
Sequencing. Do not enable multi-tenancy in the same release as initial rollout. Land single-tenant authorization, verify with the matrix, then layer Filament tenancy plus Shield's tenancy config as an isolated change. Keep shield:generate and shield:seeder out of CI/CD pipelines; they are developer commands and should only ever run locally or in a reviewed PR. Verify the "prohibited commands" safe-guard is enabled in production config — it is our protection against a stray generation run overwriting curated permissions.
Maintenance. The dominant cost is version-lockstep with Filament majors. Historical pattern is a full rewrite per Filament major, so plan for one non-trivial upgrade every ~12–18 months and pin Shield to an exact minor. Generated policies must be treated as reviewed artifacts under VCS; any drift between generated and committed state is a maintenance smell. Policy file placement differs by model location, so module/DDD layouts will need explicit Gate::policy registration maintained by hand.
Support. Community-only, no vendor SLA. GitHub issues, changelog, releases. With a single dominant maintainer, we should budget internal ownership of the integration surface (config, key convention, policy wiring) rather than assuming upstream will absorb our edge cases. Forkability under MIT is the contingency.
Scaling. Permission volume scales as resources × actions (default policy method list is 12), multiplied again by tenant count if teams are enabled. A 200-resource panel is ~2,400 permission rows and a correspondingly large role-permission join table. Two hot spots: spatie's permission cache must be reset in deploy hooks after seeding (permission:cache-reset), and the Shield admin resource itself becomes a high-value target — restrict who can reach the role-assignment UI, and consider not publishing it in tenant-facing panels.
Failure modes to instrument.
skip config for curated models.HasRoles trait or wrong auth_provider_model → authorization evaluated against the wrong model; caught by a smoke test on login.Ramp-up. For developers fluent in Filament, days — the UI and commands are discoverable and shield:setup is interactive. For security review and operations, allow one to two weeks: they need the key convention ADR, the role matrix, a runbook for seeding and cache resets, and an explicit statement of what super admin bypasses. Ship the runbook with the first release, not after the first incident.
How can I help you explore Laravel packages today?