Spatie Laravel Permission
Role and permission management package for Laravel — stores roles and permissions in database, assigns them to users, and integrates with Laravel's Gate/policy authorization system. Spatie Permission features: `$user->assignRole('admin')`, `$user->givePermissionTo('edit agents')`, `$user->hasRole('admin')`, `$user->can('edit agents')`, model-level role/permission (multiple guard support), permission inheritance (roles have permissions), permission caching, and Blade directives (@role('admin'), @can('edit agents')). Permission and role tables with has_many_through relationship. Artisan commands for role/permission seeding. The de-facto standard permission library for Laravel.
Score Breakdown
⚙ Agent Friendliness
🔒 Security
Authorization is security-critical — missing or incorrect agent permission checks create access control vulnerabilities. Always validate in controller/policy even with middleware; defense in depth. Never trust client-provided role names — validate against allowed list. Permission cache in Redis should be secured (Redis AUTH) to prevent cache poisoning attacks on agent permissions.
⚡ Reliability
Best When
Your Laravel agent platform has multiple roles and fine-grained permissions that need to be managed dynamically in database — Spatie Permission is the community standard with complete documentation and ecosystem.
Avoid When
You need resource-instance level permissions, you're not on Laravel, or your role model is simple enough for a user type enum.
Use Cases
- • Agent platform RBAC — $user->assignRole('agent-creator'); $user->givePermissionTo('deploy-agents'); permission-based agent feature gating using standard Laravel can() method throughout agent application
- • Blade permission-gated agent UI — @can('delete-agents') shows delete button only to authorized users; @role('admin') shows admin-only agent management panels; integrates with Laravel's @can directive natively
- • Agent API middleware protection — middleware(['auth:api', 'role:admin']) protects agent admin endpoints; permission middleware: middleware('permission:create-agent') restricts agent creation API to authorized service accounts
- • Permission seeding for agent platform — Artisan command php artisan db:seed --class=AgentPermissionsSeeder creates all agent permissions and admin role on fresh deployment; repeatable permission setup
- • Multi-guard agent permissions — permission guards separate web session permissions from API token permissions; givePermissionTo('create-agent', 'api') for API-specific agent creation permission separate from web UI permissions
Not For
- • Instance-level permissions — Spatie Permission is role/permission based, not resource instance based; for 'user can only edit their OWN agents', use Laravel Policies with Gate::define or combine with Spatie for role check + policy for ownership
- • Non-Laravel PHP frameworks — Spatie Permission is Laravel-specific; for Symfony or vanilla PHP agent services, use Symfony Security or custom RBAC
- • Very simple 2-role systems — if agent app has just 'user' and 'admin' with simple hard-coded checks, a column on users table is simpler than Spatie Permission database overhead
Interface
Authentication
Permission library — works with Laravel's auth system. Integrates with Sanctum, Passport, and session auth. Separate guards for API vs web agent permission checks.
Pricing
Spatie Laravel Permission is MIT licensed, maintained by Spatie. Free for all use.
Agent Metadata
Known Gotchas
- ⚠ Permission cache must be cleared after changes — Spatie caches all permissions; adding new agent permission or role via seeders/migrations requires cache clear (php artisan permission:cache-reset or app()['cache']->forget('spatie.permission.cache')); without cache clear, new permissions are invisible to running agent application
- ⚠ HasRoles trait required on User model — must add use HasRoles to User model AND the HasRoles trait from Spatie\Permission\Traits\HasRoles; without trait, $user->assignRole() throws 'Method not found'; forgetting trait is most common Spatie setup mistake for agent platform user models
- ⚠ Guard must match between permission creation and check — Permission::create(['name' => 'create-agent', 'guard_name' => 'api']); $user->givePermissionTo('create-agent') uses default guard (web); mismatched guards cause 'A permission with this name does not exist' even though permission exists in different guard for agent API
- ⚠ Super admin pattern requires Gate::before — Spatie doesn't have built-in super admin; implement via Gate::before(function ($user, $ability) { if ($user->hasRole('super-admin')) { return true; } }) in AuthServiceProvider; without Gate::before, super admin still checked against each agent permission individually
- ⚠ Wildcard permissions not built-in — Spatie Permission doesn't support glob-style permissions (agents.*); implement custom Gate checks for wildcard agent permission patterns; each agent permission must be explicitly created and assigned; design agent permission names with namespacing (agents:create, agents:delete) for organization
- ⚠ syncRoles removes all previous roles — $user->syncRoles(['admin', 'editor']) removes all existing roles and replaces with provided list; using syncRoles when intending to ADD a role removes other agent roles; use assignRole to add, removeRole to remove; syncRoles for complete replacement only
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for Spatie Laravel Permission.
Scores are editorial opinions as of 2026-03-06.