Weave Code
Nova Permission Laravel Package
bbs-lab/nova-permission
bbs-lab/nova-permission adds a Laravel Nova UI for spatie/laravel-permission, letting you create roles and permissions, assign them to users, and manage access control directly from Nova without custom admin screens.
Laravel nova permission tool.
Frequently asked questions about Nova Permission
- How do I install bbs-lab/nova-permission?
- Install it with composer require bbs-lab/nova-permission, then run php artisan migrate as usual. The package ships real PHP migration files that run automatically with your normal migrate command, so there is no separate publish step for its own schema. Only Spatie's migration remains publishable, via php artisan vendor:publish --tag="permission-migrations".
- Does nova-permission require spatie/laravel-permission?
- Yes. bbs-lab/nova-permission is an authorization and UI layer that sits on top of spatie/laravel-permission rather than a replacement for it. It extends Spatie's permission model from global role-level permissions to per-instance, granular permissions and gives you a Nova interface for creating roles and permissions, assigning them to users, and managing access control. It does not introduce a new permission engine, so your existing Spatie concepts still apply.
- Which Laravel, PHP, and Nova versions does nova-permission support?
- The package requires PHP ^8.2 and supports both Nova 4 and Nova 5 in the 2.x line. Nova 4 support was restored via a compatibility shim after having quietly broken in earlier releases, so verify it against your own Nova installation rather than assuming inherited compatibility. Note that the CI matrix runs PHP 8.3 through 8.5, meaning the PHP 8.2 floor is nominally supported but untested, so flag any environment on 8.2. Check the package's composer.json for the exact Laravel constraint.
- How do I create roles and permissions from the Nova UI?
- Once installed, the package registers a Nova tool that lets you create roles and permissions, assign them to users, and manage access control directly from the Nova admin panel. This removes the need to build custom Nova resources or admin screens for role and permission management. Actions go through Spatie's underlying models, so the data stays consistent with the rest of your authorization setup.
- How do I set up granular per-model permissions with nova-permission?
- Authenticatable models must use BBSLab\NovaPermission\Traits\HasRoles instead of Spatie's HasRoles trait, and they must implement the CanOverridePermission contract. Authorization checks against scoped, per-instance permissions then go through methods such as hasPermissionToOnModel(). Because your policies will be coupled to the package trait, plan this as a cross-cutting change that touches every authorization call site rather than an isolated package swap.
- Why is my migration failing with a duplicate entry error on the permissions unique index?
- Version 2.0.0 replaces Spatie's unique(name, guard_name) index with a composite unique index across name, guard_name, authorizable_id, and authorizable_type. Existing 1.x datasets frequently contain duplicate (name, guard_name) rows, because scoped permissions could not be created in that version and duplicates were the workaround. Audit and de-duplicate your permissions table before migrating. The explicit index name keeps things under MySQL's 64-character identifier limit, but the constraint itself will reject duplicate data.
- How do I enable the permission cache in nova-permission?
- Caching is now opt-in: the old gate_cache key is gone and config('nova-permission.cache.enabled') defaults to false. Enable it via that config value or the NOVA_PERMISSION_CACHE and NOVA_PERMISSION_CACHE_TTL environment variables. If you were relying on the previous gate cache, treat updating this config as a required post-deploy step rather than an optional one, otherwise you may see a silent performance regression.
- What breaking changes should I expect when upgrading nova-permission to v2?
- The 2.0.0 release is a stability and correctness release that turns 1.x's implicit contracts into hard requirements, with no new features. Key changes include package migrations that run automatically, the package owning the HasRoles trait, policy base class methods that now return ?bool while still accepting a Model $model parameter, the composite unique index, and caching flipped off by default. Policies that narrow the base method signatures will fail with fatal errors, so review every override before upgrading.
- Can I keep using Spatie's HasRoles trait on my User model?
- No. The package now owns the authorization trait, so authenticatable models must use BBSLab\NovaPermission\Traits\HasRoles rather than Spatie\LaravelPermission\Traits\HasRoles. Any internal code, package, or type-hint that references Spatie's trait or permission classes directly needs review after the upgrade. Swapping the import is usually simple, but the dependency coupling is what makes it risky.
- What should I check before running nova-permission in production?
- The dominant risks are upgrade-time rather than runtime, so start with a data audit of your permissions table for duplicate (name, guard_name) rows. Confirm nothing in your codebase or dependency tree consumes Spatie's HasRoles trait or type-hints against the Spatie policy classes, and review every policy override against the new ?bool return signatures. Set the cache configuration explicitly after deploying, and verify Nova 4 compatibility yourself if you are on that version. If any environment still runs PHP 8.2, flag it as untested.
Weaver
How can I help you explore Laravel packages today?