Laravel Nova Blueprint Permission Laravel Package

Getting Started

This package sits at the intersection of two things: Laravel Nova (the admin UI) and Blueprint (laravel-shift/blueprint, the YAML-driven code generator). Before writing any code, spend five minutes confirming which mode you are in — the package description reads like a runtime Nova tool ("manage roles and permissions directly from Nova"), but the published assessment and package name point to a build-time Blueprint generator that emits Nova resources and permission wiring, typically against spatie/laravel-permission. Inspect composer.json and the service provider to settle this; it changes everything below.

If it is a build-time generator (most likely):

composer require mphpmaster/laravel-nova-blueprint-permission --dev
composer require laravel-shift/blueprint --dev

Publish stubs and config so you can customise output rather than vendor-edit:

php artisan vendor:publish --provider="mPhpMaster\LaravelNovaBlueprintPermission\ServiceProvider"

Look first at:

• drafts/ at the project root — this is the input contract. Blueprint reads from here, not resources/. Most "nothing generated" reports are a wrong draft location.
• The published config/ — generator toggles, guard settings, permission naming.
• app/Nova/ after one build — the actual artefact you care about.

First use case: take an existing model in a draft, run:

php artisan blueprint:build --only=Post -v

Confirm a Nova resource lands in app/Nova/Post.php, a policy alongside it, and that the policy methods reference your permission names. That single loop — draft → build → inspect → adjust stub — is the whole day-to-day workflow.

If it turns out to be a runtime Nova tool instead: register it in NovaServiceProvider::tools() (or via the package provider), run php artisan nova:tool if it ships a tool scaffold, and validate that the roles/permissions tables from Spatie exist and are migrated before opening the UI.

Implementation Patterns

Draft-as-source-of-truth. Keep Blueprint YAML in version control and regenerate. Generate commits should show clean, reviewable diffs of Resources, Policies and migrations. If a diff is noisy, your stubs are the place to fix it, not the output.

Generate the policy, then seed from it. Don't hand-type permission strings in seeders. Let the generator emit the policy, then derive permission names from the policy methods so UI gates and seeders can never drift:

// database/seeders/PermissionSeeder.php
foreach ([Post::class, Comment::class] as $model) {
    foreach (['viewAny', 'view', 'create', 'update', 'delete'] as $action) {
        Permission::firstOrCreate(['name' => "{$action} " . class_basename($model)]);
    }
}

Assign to roles via Spatie, and attach the same names in the generated Nova resource's authorizable()/canSee() checks.

Iterate one model at a time, build fully before PR.

php artisan blueprint:build --only=Post      # tight loop while tuning
php artisan blueprint:build                  # full build catches relations/policies
git diff                                     # review before commit

Customise naming in one place. Publish stubs and pick a convention (viewAny Post vs index Post) inside the stub. The generator then applies it consistently across every resource — this is the single highest-leverage customisation you will make.

Keep hand edits outside generated files. Generated Nova resources and policies are not merge-aware. Put bespoke fields, actions and gate logic in traits or custom resource classes that the stub references, so regeneration is safe.

CI drift check.

- run: php artisan blueprint:build
- run: git diff --exit-code

This enforces that drafts are the only place Nova resources are authored, and catches "someone edited the generated file directly" before it reaches main.

Guard alignment. Check that generated policies use the same guard your app authenticates against (config/auth.php → guards, and config/permission.php → defaults.guard). If your users authenticate on api but generated policies check web, permission resolution silently fails.

Cache hygiene. If wiring to Spatie, remember permission results are cached. After seeding or changing roles in local/dev:

php artisan permission:cache-reset

Gotchas and Tips

• 3.0.0 is a major bump from 2.0.0 with no changelog body — the release note is only a compare link. Read the commit log before upgrading. Pin ^2.0 if you need runway; assume ^3.0 may change stubs, config keys, or dependency constraints (Laravel/PHP/Nova support).
• Confirm the package's actual mode before designing around it. The description implies runtime role management in Nova; the prior assessment treats it as a build-time generator. Getting this wrong means building the wrong architecture.
• Generators overwrite. Re-running blueprint:build destroys hand edits to app/Nova/* and generated policies. Never edit generated files as a habit; extend via traits/custom classes referenced by the stub.
• Dev-only dependency (if generator). Blueprint and this package belong in require-dev. Shipping them in require pushes a code-generation dependency into production with no runtime value.
• Spatie config drift. Non-default table names or a non-web default guard silently break generated policy checks. Cross-check config/permission.php against auth.guards after publishing.
• Draft location is the #1 support issue. Blueprint reads drafts/ at project root. Not resources/, not app/drafts/. Check this first when output is missing.
• Debug with -v. php artisan blueprint:build -v prints emitted file paths; it resolves most "it didn't generate" reports in one run.
• Stubs are the extension point, not vendor. Override published stubs; edits under vendor/ vanish on the next composer update.
• Test negative authorization, not just positive. Generated policies can look correct and still grant access under a different guard. Write a test that asserts a user without a role gets 403 on the Nova resource route.
• Break-glass plan. This package controls admin-plane access. Keep an artisan/tinker path to restore an admin role if a permission change or failed migration locks you out of Nova.
• Watch the maintenance signal. Three stars and sparse release notes mean you own the upgrade risk; budget a staging spike and a UAT pass on admin workflows before any major bump.