Filament Shield Laravel Package

Product Decisions This Supports

• Build vs. buy for admin-panel authorization. Any roadmap item that ships a "manage users / manage roles" screen is a recurring tax: role CRUD, permission catalogue, policy scaffolding, super-admin bypass, and the UI to administer all of it. Shield collapses that into an afternoon of configuration. The decision to make is not "do we need RBAC" — it's "do we spend two to four engineer-weeks building a permissions admin surface, or do we install this and spend that time on the differentiating feature." Default answer for a Filament shop: buy.
• Feature sequencing for internal tools and back-office panels. Because permissions are generated automatically from Filament Resources, Pages, and Widgets, a PM can approve "add a new admin module" work without a separate authorization design spike. Every new resource inherits a full permission set (viewAny, view, create, update, delete, restore, forceDelete, replicate, reorder). This directly shortens the loop between "we need an approvals screen" and "customers can use it."
• Enterprise / paid-tier readiness. Access control is a gating requirement in almost every B2B deal review and security questionnaire. Shipping role-based access with a super-admin role, per-page and per-widget permissions, and a documented permission catalogue moves you from "not yet enterprise-ready" to "shippable to a compliance-sensitive buyer" without a dedicated auth project.
• Multi-tenant SaaS scope. Native tenancy support is the deciding input on whether tenancy ships in the current quarter or gets deferred. If tenant-scoped permissions are a launch requirement, this package makes tenancy a configuration task rather than a domain-model redesign.
• Identity-provider and platform-integration strategy. The customizable permission-key builder means permission keys can be shaped to match an external system (the docs explicitly cover importing permission keys as-is from something like Keycloak). This is a real product lever: it lets you keep a single permission vocabulary across your app and your IdP instead of maintaining a translation layer. It also unlocks multi-panel and multi-resource architectures where two resources back models with the same short name — a genuine collision risk that otherwise surfaces as a security bug in production.
• Release-migration planning. Version 4 is a complete rewrite that is not backward compatible with 3.x / 4.x-beta. That is a roadmap line item, not a footnote: budget a migration and regression-test pass for any panel relying on role/permission behavior, and pin the major version in composer.json until that migration is scheduled.
• Onboarding and operational tooling. Seeder generation for roles and direct permissions means new environments, demo tenants, and customer migrations don't require hand-built permission fixtures. Fine-grained CLI tooling with command prohibiting supports repeatable deploys — relevant to how confidently you can promise self-hosted or on-prem customers a repeatable install.

When to Consider This Package

Adopt when most of these are true:

• Your application is built on Filament (this supports 4.x and 5.x on the current major) and your admin surface is where roles and permissions actually matter.
• You are already, or are willing to be, on spatie/laravel-permission. Shield is a management and generation layer on top of it, not a replacement — it is not a fit if you've chosen a different authorization substrate.
• Your permission model is role-based and resource-shaped: "can this user create invoices," "can this user see the revenue widget." This is the sweet spot.
• You need a UI for administrators to assign roles, not just code-level gates. The publishable, customizable resource is a large part of the value.
• Multi-tenancy is on the roadmap or already shipped.
• You want automatic policy generation rather than hand-writing policy classes for every model — particularly valuable with third-party or vendor resources where you'd otherwise write policies that get wiped on composer update.
• Team size or timeline makes a two-to-four-week bespoke permission system an expensive use of a senior engineer.

Look elsewhere, or plan to supplement, when:

• You are not on Filament. The entire value proposition is panel-native permission management. On plain Laravel, use spatie/laravel-permission directly.
• You need attribute- or relationship-based authorization (ABAC): "editors can only edit posts in their own department," row-level rules, time-boxed access. Shield generates the policy scaffolding, but the conditional logic is yours to write — and if that's most of your requirement, the package is doing comparatively little for you.
• You need audit logging, access reviews, or approval workflows for permission changes. Not in scope. Compliance-driven buyers will ask; plan an adjacent solution.
• You need SSO/SCIM-driven group-to-role sync as the primary mechanism. The permission-key customization helps with vocabulary alignment, but provisioning sync is a separate build.
• You are on a major version you can't migrate. If you're on Shield 3.x and can't absorb a breaking rewrite, stay put, but treat the eventual migration as scheduled technical debt rather than a surprise.
• You need field-level or API-surface-level authorization. Shield governs panel entities; API tokens, endpoint scopes, and per-column visibility are outside it.
• Single-maintainer dependency risk is unacceptable for a regulated or long-lived product. MIT license means you can fork, but budget the contingency explicitly rather than assuming it away.

Adoption criteria checklist for the go/no-go: Filament in production or committed on the roadmap; spatie/laravel-permission acceptable as the substrate; role-based (not attribute-based) model as the dominant need; a named owner for the v4 migration; and confirmation that audit logging and SSO provisioning are either out of scope or separately funded.

How to Pitch It (Stakeholders)

For executives — the one paragraph: This is a free, MIT-licensed, actively maintained package (roughly 2.8k GitHub stars, releases through mid-2026, supporting the current Filament 4.x and 5.x lines) that gives our admin panel a complete roles-and-permissions system out of the box. It replaces what is typically two to four engineer-weeks of custom security plumbing — role management screens, permission catalogues, authorization policies, super-admin handling, and multi-tenant scoping — with a configuration and setup task. The strategic upside is deal velocity: granular access control is a checkbox on nearly every enterprise security review, and this lets us answer "yes" without a dedicated project. The risks are known and manageable: it's a single-maintainer open-source dependency (mitigated by the MIT license and the option to fork), and the current major version is a deliberate breaking rewrite, so we pin the version and schedule any migration rather than absorbing it reactively. No license cost, no vendor lock-in, no data leaving our infrastructure.

For engineering — the honest summary: Shield wraps spatie/laravel-permission and auto-generates permissions and policies from your Filament Resources, Pages, and Widgets, including a deleteAny/restore/forceDelete/replicate/reorder method set, single-parameter method handling, policy merging, and vendor-model policy placement that survives composer update. It adds a super-admin role or gate interception, optional baseline panel user role, multi-tenancy, localized labels, seeder generation, and a CLI with prohibited-command safeguards. Permission keys are configurable (separator, case) and fully overridable via a buildPermissionKeyUsing callback — the escape hatch for name collisions and for adopting an external IdP's permission vocabulary verbatim. Two things to plan for: the package owns permission generation and administration, not your authorization logic — conditional, attribute-based rules stay in your policies; and the 4.x line is a non-backward-compatible rewrite, so treat the upgrade as a real migration with test coverage on role and permission behavior, and pin the major version in composer.json meanwhile.