laravel-permission

Covers Spatie Laravel Permission for role-based access control: roles and permissions, route middleware, Blade authorization directives, multi-tenant team scoping, wildcard/hierarchical permissions, super-admin bypass, cache management, direct-vs-role permission inheritance, query scopes, event-based audit logging, Policy integration, Sanctum/Passport API usage, custom models (UUID support), and testing patterns.

Laravel Permission (Spatie)

Agent Workflow (MANDATORY)

Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:

1. fuse-ai-pilot:explore-codebase - Check existing auth patterns
2. fuse-ai-pilot:research-expert - Verify Spatie Permission docs via Context7
3. 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

1. Seed roles/permissions in DatabaseSeeder
2. Cache reset after changes: php artisan permission:cache-reset
3. Use kebab-case for naming: edit-articles
4. Never hardcode role checks in controllers - use middleware
5. Set team context early in request for multi-tenant apps
6. Specify guard for API - permission:edit,api
7. 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 8.x (current 8.3, requires PHP 8.3+ and Laravel 12/13) is Laravel 13 compatible. L13 integrations:

• Upgrade v6 → v7 → v8: event classes suffixed Event (RoleAttachedEvent…), commands suffixed Command, clearClassPermissions() removed, findByName() / findOrCreate() accept BackedEnum|string (v8) — see events.md
• Cache: the permission.cache.key key stays explicit (spatie.permission.cache) in config/permission.php → unaffected by L13's switch to hyphenated prefixes
• Controller attributes: combine #[Authorize] (policy) and #[Middleware('role:admin')] (RBAC), namespace Illuminate\Routing\Attributes\Controllers — see [[laravel-blade]]
• PHP 8.3: final readonly class for custom Role/Permission DTOs

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

Best Practices

DO

• Define a single source of truth: Policy OR Permission (never both for the same action)
• Use permission:create-post (verb-noun) for clarity
• Enable teams only for genuine multi-tenancy
• Cache permissions per user (Cache::remember('user.permissions.'.$id, ...))
• Super admin via Gate::before() (never via a * wildcard permission)

DON'T

• Store permissions in the session (use the Spatie cache)
• Mix hasRole() and hasPermissionTo() without a consistent architecture
• Hardcode role names in code (use a RoleEnum enum)
• Forget to flush the cache after assignRole() in a seeder
• Grant * to a super admin (prefer a targeted Gate::before())