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é)