Filament Shield Enhanced Laravel Package

Product Decisions This Supports

• Build vs. buy for authorization UI: v0.2.0 removes the last credible reason to maintain a project-local filament-shield fork. The fork's only unique capability — HasComponentShield / transformComponents() — is now upstreamed, so "we need our own fork for component-level permissions" is no longer a valid engineering argument. This is a buy/adopt decision, not a build one.
• Granular permission model / RBAC roadmap: the package now covers three permission categories with a consistent {Prefix}:{Action}:{Subject} key format — Pages, Resources, and arbitrary Livewire components. That uniformity lets you commit to a single permission-naming convention across the admin surface rather than a per-category scheme, which simplifies both seeders and role-editing UX.
• Feature scope: shared-widget authorization: unlocks a use case previously unsupported — widgets embedded via @livewire(...) in multiple pages with no Filament panel registration. If your roadmap includes reusable dashboards, cross-page KPI cards, or embedded tools, this is the enabling capability.
• Permission-editing UX for admins: EnhancedComponentPermissionsForm plus pre-filled checkboxes in HasEnhancedRoleForm means the Role editor stays a single screen. That supports a product decision to keep role management self-service for non-engineers rather than requiring dev intervention.
• Reliability / trust in access control: the canShield() fix changes behavior from throwing to returning false when a permission row is missing (renamed action, generator not yet run). This directly affects a product decision about deploy safety: permission-denied degrades gracefully instead of producing 500s mid-deploy. Treat authorization regressions as customer-facing incidents, not internal bugs.
• Use cases now in scope: multi-tenant admin panels with per-component visibility, staged rollouts where permission generation lags code deploys, and any "hide this widget from non-admins" requirement that doesn't map to a Filament resource.

When to Consider This Package

Adopt when:

• You run Filament and need role/permission management with generated policies rather than hand-written ones.
• You have Livewire components outside any panel — shared widgets, embeds, or partials — that need distinct access rules. Before v0.2.0 this required a fork; now it doesn't.
• You are currently maintaining a filament-shield fork for component permissions. Migration path is direct: replace HasComponentShield/transformComponents() with the upstream equivalents and delete the fork.
• You need consistent permission key naming across resources, pages, and components for auditing or seeding.
• Deploy pipelines may run code before running shield:generate-enhanced-components, and you want missing permissions to deny rather than error (the v0.2.0 fix).

Look elsewhere or defer when:

• You are not on Filament — the whole value proposition is panel integration.
• You need row-level or data-scoped authorization (per-record, per-team ownership). This is capability-level, not record-level; pair with policies or use a different tool.
• Your component discovery can't be expressed via components.scan_paths — discovery is filesystem-scan based, not registry based. Unconventional layouts (generated components, vendor packages, dynamic class names) may fall outside the scan and go silently unprotected. Verify coverage before relying on it.
• You are on v0.1.x in production and the canShield() behavior change matters: code that relied on the exception being thrown (e.g. catching PermissionDoesNotExist to trigger generation) will no longer fire. That is a behavior change, not just a bugfix — audit for it.
• You want active UI/UX ownership of the Role editor beyond what the published RoleResource provides.

How to Pitch It (Stakeholders)

For executives: We can retire a custom fork of our authorization library. v0.2.0 delivers the one capability that fork existed for — per-component access control — as a supported upstream feature, with a consistent permission model across pages, resources, and components. Net effect: less bespoke code to maintain, lower upgrade risk, and one fewer internal fork tracking a third-party package. The accompanying fix also makes access checks fail closed (deny) rather than erroring when permissions are missing, which reduces the chance of a deploy-window outage in the admin panel.

For engineering: Upgrade is low-risk and removes the fork. Concretely: (1) HasComponentShield gives you canShield()/authorizeShield() with the same three-part key format as pages; (2) shield:generate-enhanced-components discovers components by scanning configurable components.scan_paths, so declare those paths explicitly and confirm coverage — there is no panel registry to fall back on; (3) EnhancedComponentPermissionsForm and HasEnhancedRoleForm pre-fill keep the Role editor unified; (4) behavior change — HasPageShield, HasResourceShield, and HasComponentShield now prefer Gate-routed can() over Spatie's hasPermissionTo()/hasAnyPermission(), so a missing permission row returns false instead of throwing PermissionDoesNotExist. Grep for any code catching that exception to trigger generation and replace it with an explicit pre-deploy shield:generate-enhanced-components step. Aligns with vanilla filament-shield's canAccess() semantics.

Ask: approve the upgrade and the fork removal in the current cycle; add permission generation to the deploy checklist so the new fail-closed behavior never surfaces as a silent lockout.