skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
fusengine/claude-plugins66 installs

laravel-permission

Use when implementing RBAC, role-based access control, or user authorization with Spatie Laravel Permission.

How do I install this agent skill?

npx skills add https://github.com/fusengine/claude-plugins --skill laravel-permission
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides a comprehensive set of templates and documentation for implementing role-based access control (RBAC) in Laravel applications using the well-known Spatie Laravel Permission package. It covers security best practices, multi-tenancy, and testing patterns.

  • Socketwarn

    1 alert: gptSecurity

  • Snykpass

    Risk: LOW · No issues

What does this agent skill do?

<objective> 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. </objective>

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.

ComponentPurpose
RoleGroup of permissions (admin, writer)
PermissionSingle ability (edit articles)
MiddlewareRoute protection
Blade DirectivesUI authorization
TeamsMulti-tenant scoping
WildcardsHierarchical permissions
Super AdminBypass all checks
EventsAudit logging (v6.15.0+)
Query ScopesFilter users by role/permission
API SupportSanctum/Passport integration
PoliciesResource-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

TopicReferenceWhen to consult
Setupspatie-permission.mdInstallation, model setup, core methods
Middlewaremiddleware.mdRoute protection patterns
Bladeblade-directives.mdUI authorization directives
Direct vs Roledirect-permissions.mdPermission inheritance

Advanced Features

TopicReferenceWhen to consult
Teamsteams.mdMulti-tenant permissions
Wildcardswildcard-permissions.mdHierarchical patterns
Super Adminsuper-admin.mdBypass all permissions
Custom Modelscustom-models.mdUUID, extending models

Integration

TopicReferenceWhen to consult
API Usageapi-usage.mdSanctum, guards, JSON responses
Policiespolicies.mdLaravel Policy integration
Query Scopesquery-scopes.mdUser::role(), User::permission()
Eventsevents.mdAudit logging, notifications

Operations & Quality

TopicReferenceWhen to consult
Cachecache.mdPerformance, debugging
CLIartisan-commands.mdArtisan commands
Testingtesting.mdTests, factories, setup
Performanceperformance.mdOptimization, N+1, caching

Templates (Code Examples)

Setup & Seeding

TemplatePurpose
UserModel.php.mdUser model with HasRoles trait
RoleSeeder.php.mdBasic role seeding
PermissionSeeder.php.mdPermission creation seeder
WildcardSeeder.php.mdHierarchical permissions

Routes & Middleware

TemplatePurpose
routes-example.mdProtected routes examples
ControllerMiddleware.php.mdMiddleware in controllers
BladeExamples.blade.mdBlade directive examples

Teams & Multi-Tenant

TemplatePurpose
TeamMiddleware.php.mdMulti-tenant middleware
TeamSeeder.php.mdTeam-scoped roles seeder
TeamModel.php.mdTeam model with boot

Super Admin & Cache

TemplatePurpose
SuperAdminSetup.php.mdGate::before bypass
CacheConfig.php.mdCache configuration
DeployScript.sh.mdCI/CD cache management

API Integration

TemplatePurpose
ApiPermissionSetup.php.mdAPI guard + Sanctum
ApiExceptionHandler.php.mdJSON error responses
ApiUserResource.php.mdUser resource with permissions

Policies & Events

TemplatePurpose
PostPolicy.php.mdPolicy with Spatie integration
PermissionEventListener.php.mdAudit event listeners
UserQueryExamples.php.mdQuery scope examples
PermissionAudit.php.mdAudit service

Testing

TemplatePurpose
PermissionTest.php.mdPest & PHPUnit tests
UserFactory.php.mdFactory with permission states

Custom Models

TemplatePurpose
CustomRole.php.mdExtended Role model
CustomPermission.php.mdExtended Permission model
UUIDMigration.php.mdUUID tables migration
SetupPermissions.php.mdCustom 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

FeatureStatusReference
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.5, 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())

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/fusengine/claude-plugins/laravel-permission">View laravel-permission on skillZs</a>