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
Advanced Features
Integration
Operations & Quality
Templates (Code Examples)
Setup & Seeding
Routes & Middleware
Teams & Multi-Tenant
Super Admin & Cache
API Integration
Policies & Events
Testing
Custom Models
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 | | |
