Nova Permission Tool Laravel Package

Getting Started

This package is a Nova UI wrapper around spatie/laravel-permission; it does not replace Spatie. Treat Spatie as the source of truth and the tool as an admin screen for roles and permissions.

1. Confirm compatibility first. The last release was April 2019, so expect Nova 1/2-era constraints, Laravel 5.8/6.x, and PHP 7.x. Do not drop it into Nova 4/Laravel 10+ without checking composer.json and testing a fork.
2. Install and configure Spatie first:

   composer require spatie/laravel-permission
   php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
   php artisan migrate
   

3. Add the tool:

   composer require digitalcloud/nova-permission-tool
   

4. Register it in app/Providers/NovaServiceProvider.php:

   public function tools()
   {
       return [
           new \DigitalCloud\NovaPermissionTool\NovaPermissionTool(),
       ];
   }
   

   Verify the exact class name in the package README or src/ if your installed version differs.
5. Publish anything the package exposes and refresh Nova assets:

   php artisan vendor:publish --provider="DigitalCloud\NovaPermissionTool\ToolServiceProvider"
   php artisan nova:publish
   php artisan migrate
   

6. First use case: seed a canonical permission list, log into Nova, open the permissions tool, create a role, attach permissions, assign that role to a user, then verify:

   $user->hasRole('editor');
   $user->can('update posts');
   

Implementation Patterns

Use a code-first permission catalogue and let the Nova UI manage role composition. Permissions are referenced by string in policies, middleware, and Blade, so uncontrolled permission creation in production is a common source of drift.

// database/seeders/PermissionSeeder.php
foreach ([
    'view users',
    'create users',
    'update users',
    'delete users',
] as $permission) {
    Permission::findOrCreate($permission, 'web');
}

Daily workflow:

• Deploy permission definitions via seeders or migrations. Use the Nova tool to create roles and attach permissions, not to invent permission names.
• Assign roles through Spatie methods in application code where possible:

  $user->syncRoles(['editor']);
  $user->givePermissionTo('publish posts');
  

• Gate Nova fields and actions with the same permission names:

  Text::make('Email')
      ->canSee(fn ($request) => $request->user()->can('view users'));
  

• Protect routes with Spatie middleware:

  Route::middleware('permission:update users')->group(function () {
      // ...
  });
  

• Use a Gate::before super-admin bypass instead of assigning every permission:

  Gate::before(function ($user, $ability) {
      return $user->hasRole('super-admin') ? true : null;
  });
  

• If the tool does not provide user-role assignment for your setup, add a Nova BelongsToMany field or a custom action that calls syncRoles.
• Keep permission names stable. Rename them in code and seeders together; otherwise existing roles retain orphaned or irrelevant permissions.
• In tests, seed the same permission catalogue and clear Spatie’s cache:

  $this->seed(PermissionSeeder::class);
  app(\Spatie\Permission\PermissionRegistrar::class)->forgetCachedPermissions();
  

Gotchas and Tips

• Abandoned-era package: low stars and no release since 2019 means you should expect compatibility work. Check composer.json constraints before installing; for modern Nova, prefer a maintained package or a small custom Nova tool.
• Guard mismatch: Spatie permissions are guard-specific. If your API uses api but the tool creates web permissions, $user->can() will fail unexpectedly. Set guard_name explicitly in seeders and config.
• Cache invalidation: Spatie caches permissions. After UI or seeder changes, clear it. Depending on the Spatie version:

  php artisan permission:cache-reset
  # older versions:
  php artisan cache:forget spatie.permission.cache
  

• Migration order: publish and run Spatie migrations before the tool’s migrations. If the tool assumes Spatie tables already exist, reversing the order causes failures.
• Teams and multi-tenancy: older Spatie versions and this tool may not support teams or tenant-scoped roles. Do not assume the UI understands team_id; test carefully or bypass the UI for team assignments.
• UUIDs/custom keys: if your users or Spatie tables use UUIDs, verify the tool’s migrations and assumptions. Hard-coded integer assumptions are common in older Nova packages.
• Deleting permissions: deleting a permission from the UI can silently break code paths that check that string. Prefer removing it from roles and code in a coordinated deploy.
• Tool authorization: Nova tools are usually visible to any Nova-authorized user unless restricted. Add a canSee/authorization check so only admins can open the permissions screen.
• Asset issues: if the tool page is blank, run php artisan nova:publish, clear config/view caches, and check the browser console and storage/logs/nova.log.
• Debugging: inspect config/permission.php, run php artisan route:list | grep -i permission, and use Tinker:

  $user->getAllPermissions()->pluck('name');
  Role::with('permissions')->get();
  

• Extension point: for anything unsupported, fork the package or replace the UI with Nova resources/actions while keeping Spatie as the backend. The package is thin UI, so falling back to Spatie directly is usually safer than patching deep internals.