Filament Guardian Laravel Package

Getting Started

• Install the package, publish its config and migrations, and run php artisan migrate. The roles/permissions tables and the super-admin role are the core of the package.
• First place to look is the package config: confirm the configured super-admin role name and that the Gate::before bypass is wired up. That bypass is what gives the super-admin role its power — and it is exactly what v1.14.0 hardens.
• Look at RolePolicy next. It governs attach/detach for normal roles, but as of v1.14.0 it no longer governs the super-admin role at all.
• First use case: seed your roles and permissions, assign one user the super-admin role, then verify that user passes every Gate/policy check. Create a second, non-super-admin user with Attach:Role/Detach:Role and confirm the Users tab on the super-admin role now hides Attach, Detach, and bulk detach.

Implementation Patterns

• Treat the super-admin role as infrastructure, not day-to-day data. Assign it via seeder or an artisan command rather than through the admin UI.
• Use RolePolicy for every non-super-admin role. Keep policy methods thin and delegate to permission checks such as Attach:Role / Detach:Role.
• In the Users tab / relation manager, rely on the package's action visibility rather than wrapping super-admin membership in your own authorization. v1.14.0 enforces this at the UI layer and should be the single source of truth.
• For delegated administration, create a separate "role manager" role that can manage other roles, and leave super-admin membership to actual super admins.
• If you need audited super-admin changes, add a custom Filament action or page that logs and requires explicit confirmation, rather than relaxing the built-in tab.
• If you cache permissions, clear that cache after role/permission changes and between tests.
• In tests, use actingAs($superAdmin) to assert the bypass, and actingAs($roleManager) to assert the Users tab hides attach/detach on the super-admin role.

Gotchas and Tips

• v1.14.0 is a behavior change. Anyone who previously relied on a non-super-admin with Attach:Role or Detach:Role to manage super-admin membership will find those actions gone from the Users tab. This is intentional, and it applies to the super-admin role regardless of what RolePolicy returns. Every other role still follows your policy as before.
• The super-admin Gate::before bypass means ordinary policy checks never run for super admins. Do not assume a RolePolicy::attach denial protects super-admin membership — it does not, and the UI now enforces that separately.
• Audit any custom code that invokes the attach/detach actions programmatically against the super-admin role. The security fix is UI-focused, but the intent is that only super admins manage that role; add explicit super-admin checks in custom actions.
• Watch for stale permission caches after upgrading. Run your cache-clear command and re-run the permission seeder if needed; otherwise old UI state can mask the change.
• Debugging visibility: if attach/detach buttons still appear for non-super-admins, confirm you are on v1.14.0+ and that the viewing user is not themselves a super admin. The check is "is super admin," not "has permission."
• Extension point: override the RoleResource or the Users relation manager if you need a different UX, but keep the super-admin guard intact — extending around it is safer than removing it.