Nova Role Manager Laravel Package

Getting Started

• Install with composer require the role-manager package, then publish its config: php artisan vendor:publish --tag=role-manager-config. The file that matters is config/role-manager.php.
• Set three things before exposing the tool to anyone:
  • role-manager.role_model — the Eloquent model used for roles (defaults to Spatie's Spatie\Permission\Models\Role). As of v1.2.1 this is what role_id validation runs against, so point it at your custom model if you have one.
  • role-manager.protected_roles — role names that must never have permissions granted or revoked through the tool (e.g. SUPER_ADMIN). Since v1.2.1 this is enforced on all write endpoints, not just save.
  • role-manager.edit_permission — the Gate ability checked before any write. Make sure a Gate/Policy actually defines it, or every write returns 403.
• First use case: open the Nova tool, pick a role, toggle a permission, confirm the change. Then immediately try toggling a permission on a protected role and confirm you get a 403 — that is the behavior v1.2.1 fixed, and it's worth verifying on your install rather than assuming.
• Where to look first in the source: the shared write guard introduced in v1.2.1 (checks edit_permission + protected_roles) and the three routes under /nova-vendor/role-manager/ — role-permissions (save), role-permissions/toggle, role-permissions/bulk-toggle.

Implementation Patterns

• Treat the three write endpoints as one surface. save, toggle, and bulk-toggle all pass through the same guard as of v1.2.1. If you add your own write route (a custom bulk action, an import command exposed over HTTP), route it through that same guard rather than re-implementing the checks — the pre-1.2.1 bug exists precisely because one endpoint did its own thing.
• Prefer the package endpoints for interactive changes, Spatie's API for seeding. Migrations, seeders, and artisan commands should call $role->givePermissionTo() / syncPermissions() directly. The HTTP endpoints are for the UI and carry the edit_permission + protected_roles semantics you don't want in a seeder.
• Custom role models: set role-manager.role_model and keep permission.table_names.roles in sync with the actual table. The two configs are independent — v1.2.1 fixed the model lookup, but the table name still comes from Spatie's config, and a mismatch surfaces as a validation failure rather than a clear error.
• Mirror the new test suite. v1.2.1 ships Pest + Orchestra Testbench tests for the role permission endpoints. If you've forked or extended the package, copy those tests as the baseline for your own integration tests — they cover the protected-role and validation paths that were previously untested.
• Front-end integration: if you're calling the endpoints from your own Vue/Livewire component instead of the shipped tool, send the same payload shape the tool sends and handle 403 distinctly from 422. A 403 now means "guard rejected" (permission or protected role); a 422 means validation, including the role_model-aware role_id check.

Gotchas and Tips

• Upgrade is urgent if you use protected_roles. Before v1.2.1, toggle and bulk-toggle skipped both the protected-role check and, per the release notes, were outside the shared guard. Anyone with tool access could grant or revoke permissions on SUPER_ADMIN with a crafted request. Audit permission changes on protected roles made since you deployed the earlier version.
• Config caching bites here. role_model is read at validation time; after changing it run php artisan config:clear (and config:cache again in production) or you'll keep validating against the old model and get confusing exists failures.
• 403 debugging is ambiguous. The shared guard returns the same response whether edit_permission failed or the role is protected. Temporarily log which branch rejected the request, or test with a known-unprotected role to isolate. Don't widen protected_roles to "fix" a 403 without checking the gate first.
• edit_permission is a Gate ability, not a role check. A Gate::before super-admin bypass still applies, which means your super admins can edit protected roles' permissions through the endpoint even though the role itself is protected — verify that's the behavior you want.
• Extension point: the shared guard is the single place to hook if you need extra policy (e.g. tenant scoping, audit logging of permission changes). Subclass or bind a replacement rather than adding checks at each endpoint, so future endpoints inherit them.
• Validation message changes: any custom form request or test asserting the literal exists:roles,id rule string will need updating; the rule is now built from your configured model.