name: laravel-permission description: Spatie Laravel Permission - roles, permissions, middleware, Blade directives, teams, wildcards, super-admin, API, testing. Use when implementing RBAC, role-based access control, or user authorization. versions: laravel: "12.46" spatie-permission: "6.24" php: "8.5" user-invocable: false references: 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.md related-skills: laravel-auth, laravel-api, laravel-testing

Laravel Permission (Spatie)

Agent Workflow (MANDATORY)

Before ANY implementation, launch in parallel:

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.

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

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