Nova Authorization Laravel Package

Getting Started

• Install with composer require opscale-co/nova-authorization. The package builds on spatie/laravel-permission and opscale-co/actions, so confirm your Nova major version and Spatie version are supported before pulling it in.
• Publish and run the package assets/migrations (php artisan vendor:publish for the nova-authorization provider tags, then php artisan migrate). If you already have Spatie’s roles/permissions tables, skip the duplicates rather than running them twice.
• The tool/resource is auto-discovered via Laravel package discovery. Look first in the Nova sidebar for the Authorization/Roles entry, then in config/nova-authorization.php (or the package README if the config filename differs) for guard, model, and UI options.
• First useful workflow: create a role (e.g. editor), attach a handful of permissions, assign the role to a test user, then log in as that user in Nova to confirm both the UI and the underlying Gate/policy checks behave as expected. This validates install, guard configuration, and cache behavior in one pass.

Implementation Patterns

• Seed permissions, don’t click them. Define the canonical permission list in a seeder using idempotent calls (Permission::findOrCreate, Role::findOrCreate) and attach with syncPermissions. This keeps local, staging, and production identical and makes the Nova UI a management surface rather than the source of truth.
• Keep one guard story. Decide whether permissions live on web, nova, or a custom guard, set it once in config, and use the same guard everywhere (seeder, policies, middleware). Nova’s guard and Spatie’s guard_name must agree or checks fail silently.
• Bridge permissions to policies. Use the package to manage role/permission data, but keep Laravel policies as the enforcement layer (viewAny, create, update, delete). A common pattern is a policy method calling $user->hasPermissionTo('posts.update'), with a Gate::before shortcut for super admins.
• Protect the management UI itself. Restrict who can see/edit roles and permissions via the package’s authorization hooks or Nova canSee/canRun methods. A user who can edit roles can effectively grant themselves anything.
• Bulk assignment via actions. Use the package’s Nova actions (backed by opscale-co/actions) for assigning permissions to roles or roles to users in batches. After the v1.2.2 dependency bump, smoke-test these actions once — the API surface is unchanged, but the transitive actions version moved to ^4.1.
• Test the authorization path, not just the UI. In feature tests, seed roles/permissions, assign them, and assert both policy results and Nova endpoint responses. Flush Spatie’s cache in test setup so role changes are visible immediately.

Gotchas and Tips

• The permission cache is the #1 source of “it didn’t work.” Spatie caches permissions; after seeding, deploying, or editing roles outside the UI, run php artisan permission:cache-reset (or forget spatie.permission.cache). Bake this into deploy scripts.
• Guard mismatches fail quietly. Permissions created with guard_name = web won’t apply when Nova checks the nova guard. Verify with $user->getAllPermissions() and inspect guard_name in the DB when a role “has” a permission but access is denied.
• Migration collisions. If Spatie’s migrations already ran, the package’s copies can conflict. Publish selectively and compare table schemas before migrating in existing environments.
• Deploy ordering. Clear config and permission caches after migrations and seeders run, not before, and avoid caching config in local development while tuning the package.
• Deleting roles is not free. Removing a role detaches it from users; check foreign-key behavior and confirm whether you want cascade cleanup or a soft “inactive” flag instead of hard deletes.
• v1.2.2 is a patch-level dependency bump only (opscale-co/actions to ^4.1). No app code changes are required. Run composer update opscale-co/actions (or a full update), then regression-test any Nova actions that assign roles or permissions.
• Extension points: override the package’s models/config when you need custom role metadata, and prefer custom Nova actions or fields over forking the tool. Keep package upgrades cheap by confining customizations to config, policies, and seeders.