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 |
majiayu000