Skip to main content
The config/permission.php file contains all configuration options for Laravel Permission. This guide documents every available option with examples and use cases.

​
Publishing the Config File

Publish the configuration file using: 
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"

​
Configuration Structure

​
Models Configuration

Define which Eloquent models to use for permissions and roles.
​
models.permission
string
default:"Spatie\\Permission\\Models\\Permission::class"
The Eloquent model used for permissions. Must implement Spatie\Permission\Contracts\Permission contract.Example:
'permission' => App\Models\Permission::class,
​
models.role
string
default:"Spatie\\Permission\\Models\\Role::class"
The Eloquent model used for roles. Must implement Spatie\Permission\Contracts\Role contract.Example:
'role' => App\Models\Role::class,

​
Table Names Configuration

Customize the database table names used by the package.
​
table_names.roles
string
default:"roles"
Table name for storing roles.Example:
'roles' => 'user_roles',
​
table_names.permissions
string
default:"permissions"
Table name for storing permissions.Example:
'permissions' => 'app_permissions',
​
table_names.model_has_permissions
string
default:"model_has_permissions"
Pivot table for model-to-permission relationships.Example:
'model_has_permissions' => 'user_permissions',
​
table_names.model_has_roles
string
default:"model_has_roles"
Pivot table for model-to-role relationships.Example:
'model_has_roles' => 'user_roles_pivot',
​
table_names.role_has_permissions
string
default:"role_has_permissions"
Pivot table for role-to-permission relationships.Example:
'role_has_permissions' => 'role_permission_pivot',

​
Column Names Configuration

Customize column names used in pivot tables and relationships.
​
column_names.role_pivot_key
string|null
default:"null"
Custom name for the role foreign key in pivot tables. Defaults to role_id when null.Example:
'role_pivot_key' => 'custom_role_id',
​
column_names.permission_pivot_key
string|null
default:"null"
Custom name for the permission foreign key in pivot tables. Defaults to permission_id when null.Example:
'permission_pivot_key' => 'custom_permission_id',
​
column_names.model_morph_key
string
default:"model_id"
The column name for the morph key in polymorphic relationships. Useful when using UUIDs.Example:
'model_morph_key' => 'model_uuid',
​
column_names.team_foreign_key
string
default:"team_id"
The foreign key column name used for teams feature.Example:
'team_foreign_key' => 'organization_id',

​
Permission Check Registration

​
register_permission_check_method
boolean
default:"true"
When enabled, registers the permission check method on Laravel’s Gate. Set to false if you want to implement custom permission checking logic.Example:
'register_permission_check_method' => false,

​
Octane Support

​
register_octane_reset_listener
boolean
default:"false"
When enabled, registers a Laravel\Octane\Events\OperationTerminated event listener that refreshes permissions on every TickTerminated, TaskTerminated, and RequestTerminated event.
This is typically only needed for specific Octane/Vapor configurations. Most applications should keep this disabled.
Example:
'register_octane_reset_listener' => true,

​
Events Configuration

​
events_enabled
boolean
default:"false"
Enable or disable permission and role assignment/unassignment events.Available Events:
  • Spatie\Permission\Events\RoleAttachedEvent
  • Spatie\Permission\Events\RoleDetachedEvent
  • Spatie\Permission\Events\PermissionAttachedEvent
  • Spatie\Permission\Events\PermissionDetachedEvent
Example:
'events_enabled' => true,
Then create event listeners:
use Spatie\Permission\Events\PermissionAttachedEvent;

Event::listen(PermissionAttachedEvent::class, function ($event) {
    Log::info('Permission attached', [
        'permission' => $event->permission->name,
        'model' => get_class($event->model),
    ]);
});

​
Teams Feature

​
teams
boolean
default:"false"
Enable multi-tenancy support using teams. When enabled, permissions and roles are scoped to teams.
Enable this BEFORE running migrations, or use the permission:setup-teams command to add team support to existing installations.
Example:
'teams' => true,
​
team_resolver
string
default:"Spatie\\Permission\\DefaultTeamResolver::class"
The class responsible for resolving the current team ID. Customize this to implement your own team resolution logic.Example:
'team_resolver' => App\Services\CustomTeamResolver::class,
Your custom resolver must implement Spatie\Permission\Contracts\PermissionsTeamResolver:
namespace App\Services;

use Spatie\Permission\Contracts\PermissionsTeamResolver;

class CustomTeamResolver implements PermissionsTeamResolver
{
    public function getTeamId(): ?int
    {
        return auth()->user()?->current_team_id;
    }
}

​
Passport Integration

​
use_passport_client_credentials
boolean
default:"false"
Enable Laravel Passport Client Credentials Grant support for checking permissions.Example:
'use_passport_client_credentials' => true,

​
Exception Messages

​
display_permission_in_exception
boolean
default:"false"
When enabled, permission names are included in authorization exception messages.
This could be considered an information leak in some security contexts. Enable only if appropriate for your application.
Example:
'display_permission_in_exception' => true,
With this enabled, exceptions will show:
User does not have the right permissions: [edit-articles, delete-articles]
​
display_role_in_exception
boolean
default:"false"
When enabled, role names are included in authorization exception messages.
This could be considered an information leak in some security contexts. Enable only if appropriate for your application.
Example:
'display_role_in_exception' => true,
With this enabled, exceptions will show:
User does not have the right roles: [admin, editor]

​
Wildcard Permissions

​
enable_wildcard_permission
boolean
default:"false"
Enable wildcard permission matching. Allows using patterns like articles.* to match articles.create, articles.edit, etc.Example:
'enable_wildcard_permission' => true,
Usage:
$user->givePermissionTo('articles.*');
$user->hasPermissionTo('articles.create'); // true
$user->hasPermissionTo('articles.edit');   // true
$user->hasPermissionTo('articles.delete'); // true
​
wildcard_permission
string
default:"Spatie\\Permission\\WildcardPermission::class"
The class used for interpreting wildcard permissions. Override to customize wildcard delimiters and matching logic.
This option is commented out by default. Uncomment and set a custom class if needed.
Example:
'wildcard_permission' => App\Services\CustomWildcardPermission::class,

​
Cache Configuration

​
cache.expiration_time
DateInterval
default:"DateInterval::createFromDateString('24 hours')"
How long permissions are cached. The cache is automatically flushed when permissions or roles are updated.Example:
'expiration_time' => \DateInterval::createFromDateString('1 hour'),
​
cache.key
string
default:"spatie.permission.cache"
The cache key used to store all permissions.Example:
'key' => 'app.permissions.cache',
​
cache.store
string
default:"default"
The cache driver to use for permission caching. Must match a store configured in config/cache.php.Example:
'store' => 'redis',

​
Complete Configuration Example

Here’s a complete example with commonly customized options:
config/permission.php
<?php

return [
    'models' => [
        'permission' => App\Models\Permission::class,
        'role' => App\Models\Role::class,
    ],

    'table_names' => [
        'roles' => 'roles',
        'permissions' => 'permissions',
        'model_has_permissions' => 'model_has_permissions',
        'model_has_roles' => 'model_has_roles',
        'role_has_permissions' => 'role_has_permissions',
    ],

    'column_names' => [
        'role_pivot_key' => null,
        'permission_pivot_key' => null,
        'model_morph_key' => 'model_id',
        'team_foreign_key' => 'team_id',
    ],

    'register_permission_check_method' => true,
    'register_octane_reset_listener' => false,
    'events_enabled' => true,
    
    'teams' => true,
    'team_resolver' => \Spatie\Permission\DefaultTeamResolver::class,
    
    'use_passport_client_credentials' => false,
    'display_permission_in_exception' => true,
    'display_role_in_exception' => true,
    'enable_wildcard_permission' => true,

    'cache' => [
        'expiration_time' => \DateInterval::createFromDateString('24 hours'),
        'key' => 'spatie.permission.cache',
        'store' => 'default',
    ],
];

​
Configuration Tips

1

Start with defaults

Begin with the default configuration and only customize what you need.
2

Teams setup

If enabling teams, do it before running migrations or use permission:setup-teams afterward.
3

Cache configuration

Consider using Redis for the cache store in production environments for better performance.
4

Clear config cache

After modifying the config file, run:
php artisan config:clear
Most applications work perfectly with the default configuration. Only customize options when you have specific requirements.

Build docs developers (and LLMs) love

Get started for freeTalk to us