Laravel Permission (Spatie) Skill

Laravel Permission (Spatie)

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Check existing auth patterns
fuse-ai-pilot:research-expert - Verify Spatie Permission docs via Context7
mcp__context7__query-docs - Check Laravel authorization patterns

After implementation, run fuse-ai-pilot:sniper for validation.

Overview

Spatie Laravel Permission provides complete role-based access control (RBAC) for Laravel applications.

| Component | Purpose | |-----------|---------| | Role | Group of permissions (admin, writer) | | Permission | Single ability (edit articles) | | Middleware | Route protection | | Blade Directives | UI authorization | | Teams | Multi-tenant scoping | | Wildcards | Hierarchical permissions | | Super Admin | Bypass all checks | | Events | Audit logging (v6.15.0+) | | Query Scopes | Filter users by role/permission | | API Support | Sanctum/Passport integration | | Policies | Resource-based authorization |

Critical Rules

Seed roles/permissions in DatabaseSeeder
Cache reset after changes: php artisan permission:cache-reset
Use kebab-case for naming: edit-articles
Never hardcode role checks in controllers - use middleware
Set team context early in request for multi-tenant apps
Specify guard for API - permission:edit,api
Clear cache in tests - Reset in setUp()/beforeEach()

Reference Guide

Core Concepts

| Topic | Reference | When to consult | |-------|-----------|-----------------| | Setup | spatie-permission.md | Installation, model setup, core methods | | Middleware | middleware.md | Route protection patterns | | Blade | blade-directives.md | UI authorization directives | | Direct vs Role | direct-permissions.md | Permission inheritance |

Advanced Features

| Topic | Reference | When to consult | |-------|-----------|-----------------| | Teams | teams.md | Multi-tenant permissions | | Wildcards | wildcard-permissions.md | Hierarchical patterns | | Super Admin | super-admin.md | Bypass all permissions | | Custom Models | custom-models.md | UUID, extending models |

Integration

| Topic | Reference | When to consult | |-------|-----------|-----------------| | API Usage | api-usage.md | Sanctum, guards, JSON responses | | Policies | policies.md | Laravel Policy integration | | Query Scopes | query-scopes.md | User::role(), User::permission() | | Events | events.md | Audit logging, notifications |

Operations & Quality

| Topic | Reference | When to consult | |-------|-----------|-----------------| | Cache | cache.md | Performance, debugging | | CLI | artisan-commands.md | Artisan commands | | Testing | testing.md | Tests, factories, setup | | Performance | performance.md | Optimization, N+1, caching |

Templates (Code Examples)

Setup & Seeding

| Template | Purpose | |----------|---------| | UserModel.php.md | User model with HasRoles trait | | RoleSeeder.php.md | Basic role seeding | | PermissionSeeder.php.md | Permission creation seeder | | WildcardSeeder.php.md | Hierarchical permissions |

Routes & Middleware

| Template | Purpose | |----------|---------| | routes-example.md | Protected routes examples | | ControllerMiddleware.php.md | Middleware in controllers | | BladeExamples.blade.md | Blade directive examples |

Teams & Multi-Tenant

| Template | Purpose | |----------|---------| | TeamMiddleware.php.md | Multi-tenant middleware | | TeamSeeder.php.md | Team-scoped roles seeder | | TeamModel.php.md | Team model with boot |

Super Admin & Cache

| Template | Purpose | |----------|---------| | SuperAdminSetup.php.md | Gate::before bypass | | CacheConfig.php.md | Cache configuration | | DeployScript.sh.md | CI/CD cache management |

API Integration

| Template | Purpose | |----------|---------| | ApiPermissionSetup.php.md | API guard + Sanctum | | ApiExceptionHandler.php.md | JSON error responses | | ApiUserResource.php.md | User resource with permissions |

Policies & Events

| Template | Purpose | |----------|---------| | PostPolicy.php.md | Policy with Spatie integration | | PermissionEventListener.php.md | Audit event listeners | | UserQueryExamples.php.md | Query scope examples | | PermissionAudit.php.md | Audit service |

Testing

| Template | Purpose | |----------|---------| | PermissionTest.php.md | Pest & PHPUnit tests | | UserFactory.php.md | Factory with permission states |

Custom Models

| Template | Purpose | |----------|---------| | CustomRole.php.md | Extended Role model | | CustomPermission.php.md | Extended Permission model | | UUIDMigration.php.md | UUID tables migration | | SetupPermissions.php.md | Custom artisan command |

Quick Reference

Assign Role

$user->assignRole('admin');

Check Permission

$user->can('edit articles');

Middleware (Web)

Route::middleware(['role:admin'])->group(fn () => ...);

Middleware (API)

Route::middleware(['auth:sanctum', 'permission:edit,api'])->group(fn () => ...);

Blade

@role('admin') ... @endrole
@can('edit articles') ... @endcan

Query Scopes

User::role('admin')->get();
User::permission('edit articles')->get();

Teams

setPermissionsTeamId($team->id);

Wildcards

$role->givePermissionTo('articles.*');

Super Admin

Gate::before(fn ($user, $ability) =>
    $user->hasRole('Super-Admin') ? true : null
);

Testing

beforeEach(fn () => app(PermissionRegistrar::class)->forgetCachedPermissions());

Feature Matrix

| Feature | Status | Reference | |---------|--------|-----------| | Basic RBAC | ✅ | spatie-permission.md | | Middleware | ✅ | middleware.md | | Blade Directives | ✅ | blade-directives.md | | Multi-Guard (web/api) | ✅ | middleware.md, api-usage.md | | Teams (Multi-Tenant) | ✅ | teams.md | | Wildcard Permissions | ✅ | wildcard-permissions.md | | Super Admin | ✅ | super-admin.md | | Cache Management | ✅ | cache.md | | Direct vs Role Perms | ✅ | direct-permissions.md | | Artisan Commands | ✅ | artisan-commands.md | | UUID Support | ✅ | custom-models.md | | Custom Models | ✅ | custom-models.md | | Events (v6.15.0+) | ✅ | events.md | | Query Scopes | ✅ | query-scopes.md | | Policy Integration | ✅ | policies.md | | API / Sanctum | ✅ | api-usage.md | | Testing | ✅ | testing.md | | Performance | ✅ | performance.md |

Laravel 13 Notes

Spatie Permission 6.24 est compatible Laravel 13. Intégrations L13 :

Cache prefix hyphens : spatie.permission.cache devient spatie-permission-cache ; configurer permission.cache.key si rétro-compat requise
Attributes Controllers : combiner #[Authorize] (policy) et #[Middleware('role:admin')] (RBAC) — voir [[laravel-blade]]
PHP 8.3 : final readonly class pour Role/Permission DTOs custom

#[Middleware(['auth', 'role:admin|editor'])]
#[Authorize('update', Post::class)]
public function update(UpdatePostRequest $request, Post $post) { /* ... */ }

Best Practices

DO

Définir une seule source de vérité : Policy OU Permission (pas les deux pour la même action)
Utiliser permission:create-post (verb-noun) pour clarté
Activer teams uniquement si réel multi-tenant
Cacher les permissions par utilisateur (Cache::remember('user.permissions.'.$id, ...))
Super admin via Gate::before() (jamais via permission wildcard *)

DON'T

Stocker permissions en session (utiliser le cache Spatie)
Mixer hasRole() et hasPermissionTo() sans cohérence d'architecture
Hardcoder noms de rôles dans le code (utiliser enum RoleEnum)
Oublier de purger le cache après assignRole() en seeder
Donner * à un super admin (préférer Gate::before() ciblé)

Agent Skills: Laravel Permission (Spatie)

Install this agent skill to your local

Skill Files