Nova Permission Laravel Package

Product Decisions This Supports

Feature: per-record (granular) permission control inside Nova

• Enables the "can this user edit this record?" capability — approvals, ownership-scoped resources, per-tenant or per-team administration — surfaced through a Nova UI rather than custom admin screens.
• The permission builder, role assignment, and general/per-instance permission distinction ship with the package; the seed data in the workbench (admin/writer/reader, Post vs Service) is a usable reference model for scoping a first feature.
• v2.0.0 is the first release where the granular capability actually works: 1.x shipped the feature but could not create a same-name scoped permission (Spatie's unique(name, guard_name) was never replaced) and filtered on a hardcoded chambers.id column from another project. Any roadmap item or customer commitment resting on granular permissions in 1.x is effectively unmet and must be re-baselined against 2.x.

Build vs. buy

• The build alternative is a policy layer plus a per-model authorization table plus a Nova UI plus a cache-invalidation story — this package bundles all four, so "buy" is defensible for anything short of a permissions system that is the product.
• The buy case got materially stronger: a suite of tests (Pest, 100% line coverage, mutation testing, architecture tests), PHPStan level 8, Pint, and a CI matrix (Nova 4/5 × Laravel 11–13 × PHP 8.3–8.5) is the evidence a PM needs to accept a small-vendor dependency for authorization, which is otherwise a red flag.
• The buy case also carries a cost: the package demands its own trait (HasRoles) and contract (CanOverridePermission) on the authenticatable model, and its policies call hasPermissionToOnModel(). That is a one-way door on the user model and on every policy that touches these resources — worth deciding deliberately, not as a side effect of a sprint.

Roadmap and platform timing

• v2.0.0 is a hard platform gate: PHP ^8.2, Nova ^4.0 || ^5.0, spatie/laravel-permission ^6. On Nova 3, PHP 8.1, or Spatie 5, this is not adoptable without a platform upgrade first — sequence it behind (or bundle it with) the Nova 4/5 migration, not in parallel with it.
• Nova 4 support was silently broken in 1.x and is restored here. If Nova 4 is the current standard, that is a blocker lifted, not a nice-to-have.
• Gate cache is now opt-in and off by default (config('nova-permission.cache.enabled'), NOVA_PERMISSION_CACHE / NOVA_PERMISSION_CACHE_TTL). Defaults changed from caching to not caching — expect a latency regression on authorization-heavy screens and budget a follow-up ticket to enable the cache with a tuned TTL, rather than discovering it in production.
• Package migrations are now real .php files that auto-run on php artisan migrate, and only Spatie's migration is published under --tag="permission-migrations". This is a deployment-governance decision: schema changes to the authorization table (including the new composite unique index) will arrive with ordinary deploys, so review them the way you review a first-party migration.

Upgrade decision (1.x → 2.x)

• Treat as a migration project, not a version bump: swap to the package's HasRoles trait, implement CanOverridePermission, re-point the gate_cache config key to the new cache section, and stop narrowing the base Policy signatures (?bool, keep the Model $model parameter). Allocating a short, explicit spike here is cheaper than debugging authorization gaps later.
• If 1.x is in production and granular permissions were never trusted (or were quietly worked around), the honest options are: upgrade now and delete the workarounds, or freeze 1.x and remove the dead dependency. Continuing to run 1.x for a feature that didn't function is the worst of the three.

When to Consider This Package

Adopt when:

• You are on Laravel Nova 4 or 5, PHP 8.2+, and spatie/laravel-permission 6 — or are already committed to that upgrade and can fold this in.
• The product needs permissions scoped to a specific record (per-post, per-service, per-tenant object), not just "role X can do action Y globally." This package's entire differentiation is that distinction.
• Administrators — not engineers — are expected to author roles and permissions. The Nova permission builder is the product surface, and the v2 search/debounce/loading fixes matter because that UI is the workflow.
• You accept the integration contract on the user model and policies and can enforce it consistently across the codebase.
• A small-vendor dependency is acceptable given the quality signals above; you want the per-model cache invalidation and authorization-cache handling already solved rather than re-derived.

Look elsewhere or defer when:

• Global, role-based permissions are all you need. Plain spatie/laravel-permission plus Laravel policies is less surface area, no trait lock-in, and no auto-running migrations.
• You need per-record abilities but not a Nova admin UI — spatie teams, a custom policy + pivot table, or a per-model authorization library may be lighter and avoids the HasRoles/CanOverridePermission contract entirely.
• Any part of the platform floor is missing (Nova 3, PHP 8.1, Spatie 5) and the upgrade is not already on the roadmap.
• You require vendor SLAs, a commercial support path, or a maintainer team of more than one — this is a single-org package (BBS-Lab); the CI matrix and mutation testing reduce but do not remove that risk.
• You cannot tolerate migrations running implicitly during php artisan migrate, or need a schema you control end-to-end on the authorization table.
• Authorization caching is load-bearing from day one and you cannot absorb a period with the cache disabled by default.

Adoption guardrails worth writing into the ticket: pin the major version explicitly, run the upgrade guide against a branch with the full permission matrix exercised, verify the composite unique index (name, guard_name, authorizable_id, authorizable_type) applies cleanly on MySQL (the index name is explicit for this reason), and add a regression test that a same-name permission can exist on two different model instances — that is precisely the failure mode 1.x had.

How to Pitch It (Stakeholders)

For executives (one paragraph): We are evaluating a Nova package that lets administrators grant permissions on individual records rather than only across the whole application — the difference between "writers can edit posts" and "this writer can edit this post." The previous version advertised that capability but it did not work; the new v2.0.0 makes it work, adds a real test suite and CI, and modernizes the stack. The cost is a mandatory platform floor (PHP 8.2+, Nova 4/5, Spatie 6) and a non-trivial upgrade if we are already on 1.x. Recommendation: adopt only as part of the Nova 4/5 upgrade, not as a standalone project, and treat it as a buy decision that saves us building an admin permissions UI and a caching layer ourselves — with the residual risk that it is a small-vendor dependency in a security-sensitive part of the system.

For engineering (the short version): This is a correctness release, not a feature release. The headline is that granular permissions were dead in 1.x — same-name scoped permissions could not be inserted (Spatie's unique(name, guard_name) was never replaced) and scoping filtered on a hardcoded chambers.id. If we ever shipped against that, our assumptions were wrong.

Breaking changes to plan for: PHP ^8.2, Nova ^4.0 || ^5.0, Spatie ^6; the authenticatable model must use the package's HasRoles trait and implement CanOverridePermission (policies call hasPermissionToOnModel()); package migrations now auto-run on php artisan migrate and are no longer publishable except Spatie's; gate_cache is replaced by an opt-in cache section defaulting to disabled; base Policy methods return ?bool and keep the Model $model parameter, so don't narrow them in overrides.

Also fixed and worth knowing: Nova 4 support restored (the Nova-5-only devtool dependencies were removed), the permission builder search now actually filters, and per-model authorization-cache invalidation is corrected. The quality bar is now Pest with 100% line coverage plus mutation and architecture tests, PHPStan level 8, Pint, and a CI matrix across Nova 4/5, Laravel 11–13, PHP 8.3–8.5 — that is the reason to trust it more than 1.x, and also the reason a 1.x→2.x jump deserves its own branch and a permission-matrix regression test rather than a same-day merge.