Panel Roles Laravel Package

Product Decisions This Supports

• Admin user-management features in Filament panels. The plugin sits in the "who can assign which roles" slice of the admin experience — relevant if your roadmap includes inviting users, promoting users, or delegating admin access from inside the product rather than through the database.
• Build vs. buy on RBAC plumbing. The assignment/restriction logic here is small but easy to get subtly wrong (privilege escalation is the classic failure mode). Buying a ~one-class plugin can be cheaper than owning that logic, provided you're already on Filament and satisfied by its role model.
• Privilege-escalation guardrails. v0.0.3 makes roleToAssign and restrictedRoles mandatory rather than implicit. That is a product-level safety decision: the panel cannot silently fall back to a permissive default, so an admin who can manage users cannot accidentally mint a super-admin. This supports decisions about how much self-serve administration you're willing to expose to customers vs. keep internal.
• Scope discipline. It is a thin configuration surface, not a permissions framework. That supports a decision to not adopt it as your authorization layer — use it for the assignment UI, keep policy/gate enforcement in your own code (or spatie/laravel-permission).
• Not supported: multi-tenant role scoping, per-team permissions, audit trails of who granted what. If those are on the roadmap, this package is at most a stopgap.

When to Consider This Package

Consider it when all of the following hold:

• You are building on Filament and want role assignment inside the panel with minimal wiring.
• Your role model is flat (a user has a role; some roles are off-limits) rather than hierarchical, team-scoped, or permission-granular.
• You are comfortable with a 0.0.x package: no semver stability guarantee, breaking changes on minor bumps (v0.0.3 is itself a breaking change requiring new mandatory config), and a very small maintainer surface.
• The blast radius of a bug is internal admin tooling, not customer-facing authorization decisions.
• You are willing to pin the version and read release notes on upgrade.

Look elsewhere when:

• You need fine-grained permissions (per-resource, per-action, per-tenant) — go to spatie/laravel-permission plus Laravel policies/gates, and build the assignment UI yourself.
• You need auditability (who assigned which role, when) for compliance — nothing here suggests that's covered; you'd be adding it.
• You are not on Filament, or you're on a Filament major version outside the package's tested range.
• Role assignment is customer-facing or revenue-critical — a 0.0.x dependency at that layer is an avoidable risk.
• You want multiple roles per user or role hierarchies; the API (roleToAssign singular, restrictedRoles) reads as one-role-per-user with a denylist.

Adoption checklist: pin the exact version, add a smoke test asserting a restricted role cannot be assigned, document the restrictedRoles list as a reviewed security control (not a config detail), and confirm it fails closed when misconfigured.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost Filament plugin that lets staff manage user roles from inside the admin panel. The latest release removes a footgun: you must now explicitly declare which role gets assigned and which roles are off-limits, so a misconfiguration can't quietly hand out admin access. Cost is negligible; the main consideration is maturity — it's a pre-1.0 package with a single maintainer, so it belongs in internal admin tooling, not in customer-facing access control.

To engineering: One class, configured per panel. The v0.0.3 change is breaking but directionally right — configuration is now explicit and fails loudly instead of defaulting to something permissive. Pin the version, add a test that a restrictedRoles entry is rejected on assignment, and treat the restricted list as a security-reviewed artifact. It is not an authorization layer: keep gates/policies (or spatie/laravel-permission) as the enforcement point and use this only for the assignment surface. If requirements grow toward multi-tenant or per-permission roles, expect to replace it — budget that as a known exit, not a surprise.