Laravel Permission (Spatie)
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- 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é)
1---2name: laravel-permission3description: Use when implementing RBAC, role-based access control, or user authorization with Spatie Laravel Permission.4versions:5 laravel: "13.0"6 spatie-permission: "6.24"7 php: "8.3"8user-invocable: false9references: references/spatie-permission.md, references/middleware.md, references/blade-directives.md, references/teams.md, references/wildcard-permissions.md, references/super-admin.md, references/cache.md, references/direct-permissions.md, references/artisan-commands.md, references/custom-models.md, references/events.md, references/query-scopes.md, references/policies.md, references/api-usage.md, references/testing.md, references/performance.md10related-skills: laravel-auth, laravel-api, laravel-testing11metadata:12 source: https://skillmd.com/skills/fusengine/laravel-permission13---1415<objective>16Covers Spatie Laravel Permission for role-based access control: roles and17permissions, route middleware, Blade authorization directives, multi-tenant18team scoping, wildcard/hierarchical permissions, super-admin bypass, cache19management, direct-vs-role permission inheritance, query scopes,20event-based audit logging, Policy integration, Sanctum/Passport API usage,21custom models (UUID support), and testing patterns.22</objective>2324# Laravel Permission (Spatie)2526## Agent Workflow (MANDATORY)2728Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:29301. **fuse-ai-pilot:explore-codebase** - Check existing auth patterns312. **fuse-ai-pilot:research-expert** - Verify Spatie Permission docs via Context7323. **mcp__context7__query-docs** - Check Laravel authorization patterns3334After implementation, run **fuse-ai-pilot:sniper** for validation.3536---3738## Overview3940Spatie Laravel Permission provides complete role-based access control (RBAC) for Laravel applications.4142| Component | Purpose |43|-----------|---------|44| **Role** | Group of permissions (admin, writer) |45| **Permission** | Single ability (edit articles) |46| **Middleware** | Route protection |47| **Blade Directives** | UI authorization |48| **Teams** | Multi-tenant scoping |49| **Wildcards** | Hierarchical permissions |50| **Super Admin** | Bypass all checks |51| **Events** | Audit logging (v6.15.0+) |52| **Query Scopes** | Filter users by role/permission |53| **API Support** | Sanctum/Passport integration |54| **Policies** | Resource-based authorization |5556---5758## Critical Rules59601. **Seed roles/permissions** in `DatabaseSeeder`612. **Cache reset** after changes: `php artisan permission:cache-reset`623. **Use kebab-case** for naming: `edit-articles`634. **Never hardcode** role checks in controllers - use middleware645. **Set team context** early in request for multi-tenant apps656. **Specify guard for API** - `permission:edit,api`667. **Clear cache in tests** - Reset in setUp()/beforeEach()6768---6970## Reference Guide7172### Core Concepts7374| Topic | Reference | When to consult |75|-------|-----------|-----------------|76| **Setup** | [spatie-permission.md](references/spatie-permission.md) | Installation, model setup, core methods |77| **Middleware** | [middleware.md](references/middleware.md) | Route protection patterns |78| **Blade** | [blade-directives.md](references/blade-directives.md) | UI authorization directives |79| **Direct vs Role** | [direct-permissions.md](references/direct-permissions.md) | Permission inheritance |8081### Advanced Features8283| Topic | Reference | When to consult |84|-------|-----------|-----------------|85| **Teams** | [teams.md](references/teams.md) | Multi-tenant permissions |86| **Wildcards** | [wildcard-permissions.md](references/wildcard-permissions.md) | Hierarchical patterns |87| **Super Admin** | [super-admin.md](references/super-admin.md) | Bypass all permissions |88| **Custom Models** | [custom-models.md](references/custom-models.md) | UUID, extending models |8990### Integration9192| Topic | Reference | When to consult |93|-------|-----------|-----------------|94| **API Usage** | [api-usage.md](references/api-usage.md) | Sanctum, guards, JSON responses |95| **Policies** | [policies.md](references/policies.md) | Laravel Policy integration |96| **Query Scopes** | [query-scopes.md](references/query-scopes.md) | `User::role()`, `User::permission()` |97| **Events** | [events.md](references/events.md) | Audit logging, notifications |9899### Operations & Quality100101| Topic | Reference | When to consult |102|-------|-----------|-----------------|103| **Cache** | [cache.md](references/cache.md) | Performance, debugging |104| **CLI** | [artisan-commands.md](references/artisan-commands.md) | Artisan commands |105| **Testing** | [testing.md](references/testing.md) | Tests, factories, setup |106| **Performance** | [performance.md](references/performance.md) | Optimization, N+1, caching |107108---109110### Templates (Code Examples)111112#### Setup & Seeding113| Template | Purpose |114|----------|---------|115| [UserModel.php.md](references/templates/UserModel.php.md) | User model with HasRoles trait |116| [RoleSeeder.php.md](references/templates/RoleSeeder.php.md) | Basic role seeding |117| [PermissionSeeder.php.md](references/templates/PermissionSeeder.php.md) | Permission creation seeder |118| [WildcardSeeder.php.md](references/templates/WildcardSeeder.php.md) | Hierarchical permissions |119120#### Routes & Middleware121| Template | Purpose |122|----------|---------|123| [routes-example.md](references/templates/routes-example.md) | Protected routes examples |124| [ControllerMiddleware.php.md](references/templates/ControllerMiddleware.php.md) | Middleware in controllers |125| [BladeExamples.blade.md](references/templates/BladeExamples.blade.md) | Blade directive examples |126127#### Teams & Multi-Tenant128| Template | Purpose |129|----------|---------|130| [TeamMiddleware.php.md](references/templates/TeamMiddleware.php.md) | Multi-tenant middleware |131| [TeamSeeder.php.md](references/templates/TeamSeeder.php.md) | Team-scoped roles seeder |132| [TeamModel.php.md](references/templates/TeamModel.php.md) | Team model with boot |133134#### Super Admin & Cache135| Template | Purpose |136|----------|---------|137| [SuperAdminSetup.php.md](references/templates/SuperAdminSetup.php.md) | Gate::before bypass |138| [CacheConfig.php.md](references/templates/CacheConfig.php.md) | Cache configuration |139| [DeployScript.sh.md](references/templates/DeployScript.sh.md) | CI/CD cache management |140141#### API Integration142| Template | Purpose |143|----------|---------|144| [ApiPermissionSetup.php.md](references/templates/ApiPermissionSetup.php.md) | API guard + Sanctum |145| [ApiExceptionHandler.php.md](references/templates/ApiExceptionHandler.php.md) | JSON error responses |146| [ApiUserResource.php.md](references/templates/ApiUserResource.php.md) | User resource with permissions |147148#### Policies & Events149| Template | Purpose |150|----------|---------|151| [PostPolicy.php.md](references/templates/PostPolicy.php.md) | Policy with Spatie integration |152| [PermissionEventListener.php.md](references/templates/PermissionEventListener.php.md) | Audit event listeners |153| [UserQueryExamples.php.md](references/templates/UserQueryExamples.php.md) | Query scope examples |154| [PermissionAudit.php.md](references/templates/PermissionAudit.php.md) | Audit service |155156#### Testing157| Template | Purpose |158|----------|---------|159| [PermissionTest.php.md](references/templates/PermissionTest.php.md) | Pest & PHPUnit tests |160| [UserFactory.php.md](references/templates/UserFactory.php.md) | Factory with permission states |161162#### Custom Models163| Template | Purpose |164|----------|---------|165| [CustomRole.php.md](references/templates/CustomRole.php.md) | Extended Role model |166| [CustomPermission.php.md](references/templates/CustomPermission.php.md) | Extended Permission model |167| [UUIDMigration.php.md](references/templates/UUIDMigration.php.md) | UUID tables migration |168| [SetupPermissions.php.md](references/templates/SetupPermissions.php.md) | Custom artisan command |169170---171172## Quick Reference173174### Assign Role175```php176$user->assignRole('admin');177```178179### Check Permission180```php181$user->can('edit articles');182```183184### Middleware (Web)185```php186Route::middleware(['role:admin'])->group(fn () => ...);187```188189### Middleware (API)190```php191Route::middleware(['auth:sanctum', 'permission:edit,api'])->group(fn () => ...);192```193194### Blade195```blade196@role('admin') ... @endrole197@can('edit articles') ... @endcan198```199200### Query Scopes201```php202User::role('admin')->get();203User::permission('edit articles')->get();204```205206### Teams207```php208setPermissionsTeamId($team->id);209```210211### Wildcards212```php213$role->givePermissionTo('articles.*');214```215216### Super Admin217```php218Gate::before(fn ($user, $ability) =>219 $user->hasRole('Super-Admin') ? true : null220);221```222223### Testing224```php225beforeEach(fn () => app(PermissionRegistrar::class)->forgetCachedPermissions());226```227228---229230## Feature Matrix231232| Feature | Status | Reference |233|---------|--------|-----------|234| Basic RBAC | ✅ | spatie-permission.md |235| Middleware | ✅ | middleware.md |236| Blade Directives | ✅ | blade-directives.md |237| Multi-Guard (web/api) | ✅ | middleware.md, api-usage.md |238| Teams (Multi-Tenant) | ✅ | teams.md |239| Wildcard Permissions | ✅ | wildcard-permissions.md |240| Super Admin | ✅ | super-admin.md |241| Cache Management | ✅ | cache.md |242| Direct vs Role Perms | ✅ | direct-permissions.md |243| Artisan Commands | ✅ | artisan-commands.md |244| UUID Support | ✅ | custom-models.md |245| Custom Models | ✅ | custom-models.md |246| Events (v6.15.0+) | ✅ | events.md |247| Query Scopes | ✅ | query-scopes.md |248| Policy Integration | ✅ | policies.md |249| API / Sanctum | ✅ | api-usage.md |250| Testing | ✅ | testing.md |251| Performance | ✅ | performance.md |252253---254255## Laravel 13 Notes256257Spatie Permission 6.24 est **compatible Laravel 13**. Intégrations L13 :258259- **Cache prefix hyphens** : `spatie.permission.cache` devient `spatie-permission-cache` ; configurer `permission.cache.key` si rétro-compat requise260- **Attributes Controllers** : combiner `#[Authorize]` (policy) et `#[Middleware('role:admin')]` (RBAC) — voir [[laravel-blade]]261- **PHP 8.3** : `final readonly class` pour Role/Permission DTOs custom262263```php264#[Middleware(['auth', 'role:admin|editor'])]265#[Authorize('update', Post::class)]266public function update(UpdatePostRequest $request, Post $post) { /* ... */ }267```268269## Best Practices270271### DO272- Définir une seule source de vérité : Policy OU Permission (pas les deux pour la même action)273- Utiliser `permission:create-post` (verb-noun) pour clarté274- Activer `teams` uniquement si réel multi-tenant275- Cacher les permissions par utilisateur (`Cache::remember('user.permissions.'.$id, ...)`)276- Super admin via `Gate::before()` (jamais via permission wildcard `*`)277278### DON'T279- Stocker permissions en session (utiliser le cache Spatie)280- Mixer `hasRole()` et `hasPermissionTo()` sans cohérence d'architecture281- Hardcoder noms de rôles dans le code (utiliser enum `RoleEnum`)282- Oublier de purger le cache après `assignRole()` en seeder283- Donner `*` à un super admin (préférer `Gate::before()` ciblé)