Skip to main content
The Permission model represents a single permission in the system. It extends Laravel’s Eloquent Model and implements the Spatie\Permission\Contracts\Permission interface.

​
Properties

​
id
int|string
The primary key of the permission
​
name
string
The name of the permission
​
guard_name
string
The guard name associated with this permission
​
created_at
?\Illuminate\Support\Carbon
Timestamp when the permission was created
​
updated_at
?\Illuminate\Support\Carbon
Timestamp when the permission was last updated

​
Relationships

​
roles
\Illuminate\Database\Eloquent\Collection
Collection of roles that have this permission
​
users
\Illuminate\Database\Eloquent\Collection
Collection of users who have this permission directly assigned

​
Static Methods

​
create

Create a new permission.
​
attributes
array
default:"[]"
An array of attributes for the permission. Must include name. If guard_name is not provided, the default guard will be used.
​
return
Permission
The newly created permission instance
$permission = Permission::create([
    'name' => 'edit articles',
    'guard_name' => 'web'
]);
Throws PermissionAlreadyExists if a permission with the same name and guard already exists.

​
findByName

Find a permission by its name and optionally guard name.
​
name
string
required
The name of the permission to find
​
guardName
string|null
default:"null"
The guard name. If not provided, the default guard will be used.
​
return
Permission
The permission instance
$permission = Permission::findByName('edit articles');
$permission = Permission::findByName('edit articles', 'api');
Throws PermissionDoesNotExist if the permission is not found.

​
findById

Find a permission by its ID and optionally guard name.
​
id
int|string
required
The ID of the permission to find
​
guardName
string|null
default:"null"
The guard name. If not provided, the default guard will be used.
​
return
Permission
The permission instance
$permission = Permission::findById(1);
$permission = Permission::findById(1, 'api');
Throws PermissionDoesNotExist if the permission is not found.

​
findOrCreate

Find an existing permission or create a new one.
​
name
string
required
The name of the permission
​
guardName
string|null
default:"null"
The guard name. If not provided, the default guard will be used.
​
return
Permission
The found or newly created permission instance
$permission = Permission::findOrCreate('edit articles');
$permission = Permission::findOrCreate('edit articles', 'api');

​
Instance Methods

​
roles

Get all roles that have this permission.
​
return
\Illuminate\Database\Eloquent\Relations\BelongsToMany
A BelongsToMany relationship to the Role model
$roles = $permission->roles;
$roleCount = $permission->roles()->count();

​
users

Get all users who have this permission directly assigned (not via roles).
​
return
\Illuminate\Database\Eloquent\Relations\BelongsToMany
A BelongsToMany relationship to the User model
$users = $permission->users;
$userCount = $permission->users()->count();

​
Methods from HasRoles Trait

​
assignRole

Assign one or more roles to this permission.
​
roles
string|int|array|Role|Collection|BackedEnum
required
One or more roles to assign (can be role name, ID, model instance, or array/collection of these)
​
return
$this
The permission instance for method chaining
$permission->assignRole('writer');
$permission->assignRole(['writer', 'editor']);
$permission->assignRole(1, 2, 3);

​
removeRole

Remove one or more roles from this permission.
​
roles
string|int|array|Role|Collection|BackedEnum
required
One or more roles to remove
​
return
$this
The permission instance for method chaining
$permission->removeRole('writer');
$permission->removeRole(['writer', 'editor']);

​
syncRoles

Remove all current roles and assign the given ones.
​
roles
string|int|array|Role|Collection|BackedEnum
required
One or more roles to sync
​
return
$this
The permission instance for method chaining
$permission->syncRoles(['writer', 'editor']);
$permission->syncRoles('writer');

​
hasRole

Check if the permission has any of the given roles.
​
roles
string|int|array|Role|Collection|BackedEnum
required
One or more roles to check
​
guard
string|null
default:"null"
The guard name to filter by
​
return
bool
True if the permission has any of the given roles
if ($permission->hasRole('writer')) {
    // Permission has the writer role
}

if ($permission->hasRole(['writer', 'editor'])) {
    // Permission has at least one of these roles
}

​
hasAllRoles

Check if the permission has all of the given roles.
​
roles
string|array|Role|Collection|BackedEnum
required
One or more roles to check
​
guard
string|null
default:"null"
The guard name to filter by
​
return
bool
True if the permission has all of the given roles
if ($permission->hasAllRoles(['writer', 'editor'])) {
    // Permission has both roles
}

​
hasAnyRole

Alias to hasRole() but without guard controls.
​
roles
string|int|array|Role|Collection|BackedEnum
required
One or more roles to check
​
return
bool
True if the permission has any of the given roles
if ($permission->hasAnyRole('writer', 'editor')) {
    // Permission has at least one of these roles
}

​
hasExactRoles

Check if the permission has exactly the given roles and no more.
​
roles
string|array|Role|Collection|BackedEnum
required
One or more roles to check
​
guard
string|null
default:"null"
The guard name to filter by
​
return
bool
True if the permission has exactly these roles
if ($permission->hasExactRoles(['writer', 'editor'])) {
    // Permission has exactly these two roles, no more, no less
}

​
getDirectPermissions

Get all permissions directly coupled to the permission model.
​
return
\Illuminate\Support\Collection
Collection of permissions
$permissions = $permission->getDirectPermissions();

​
getRoleNames

Get the names of all roles assigned to this permission.
​
return
\Illuminate\Support\Collection
Collection of role names
$roleNames = $permission->getRoleNames();
// ['writer', 'editor']

​
Query Scopes

​
role

Scope the query to permissions that have certain roles.
​
roles
string|int|array|Role|Collection|BackedEnum
required
One or more roles to filter by
​
guard
string|null
default:"null"
The guard name to filter by
$permissions = Permission::role('writer')->get();
$permissions = Permission::role(['writer', 'editor'])->get();

​
withoutRole

Scope the query to permissions that don’t have certain roles.
​
roles
string|int|array|Role|Collection|BackedEnum
required
One or more roles to exclude
​
guard
string|null
default:"null"
The guard name to filter by
$permissions = Permission::withoutRole('admin')->get();

​
Configuration

The Permission model uses the following configuration options:
  • permission.table_names.permissions - The database table name (default: permissions)
  • permission.models.role - The Role model class to use for relationships
  • permission.table_names.role_has_permissions - The pivot table for role-permission relationships
  • permission.table_names.model_has_permissions - The pivot table for direct user-permission relationships

​
Events

The following events are fired when roles are attached/detached:
  • Spatie\Permission\Events\RoleAttachedEvent - Fired when a role is assigned
  • Spatie\Permission\Events\RoleDetachedEvent - Fired when a role is removed

Build docs developers (and LLMs) love

Get started for freeTalk to us