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