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

​
Properties

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

​
Relationships

​
permissions
\Illuminate\Database\Eloquent\Collection
Collection of permissions assigned to this role
​
users
\Illuminate\Database\Eloquent\Collection
Collection of users who have this role

​
Static Methods

​
create

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

​
findByName

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

​
findById

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

​
findOrCreate

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

​
Instance Methods

​
permissions

Get all permissions assigned to this role.
​
return
\Illuminate\Database\Eloquent\Relations\BelongsToMany
A BelongsToMany relationship to the Permission model
$permissions = $role->permissions;
$permissionCount = $role->permissions()->count();

​
users

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

​
hasPermissionTo

Determine if the role has the given permission.
​
permission
string|int|Permission|BackedEnum
required
The permission to check (can be permission name, ID, model instance, or enum)
​
guardName
string|null
default:"null"
The guard name. If not provided, the role’s guard will be used.
​
return
bool
True if the role has the permission
if ($role->hasPermissionTo('edit articles')) {
    // Role has the permission
}

if ($role->hasPermissionTo(1)) {
    // Check by permission ID
}
Throws PermissionDoesNotExist if the permission doesn’t exist or GuardDoesNotMatch if guards don’t match.

​
Methods from HasPermissions Trait

​
givePermissionTo

Grant one or more permissions to this role.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to grant (can be permission name, ID, model instance, or array/collection of these)
​
return
$this
The role instance for method chaining
$role->givePermissionTo('edit articles');
$role->givePermissionTo(['edit articles', 'delete articles']);
$role->givePermissionTo(1, 2, 3);

​
syncPermissions

Remove all current permissions and assign the given ones.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to sync
​
return
$this
The role instance for method chaining
$role->syncPermissions(['edit articles', 'delete articles']);
$role->syncPermissions('edit articles');

​
revokePermissionTo

Revoke one or more permissions from this role.
​
permission
Permission|Permission[]|string|string[]|BackedEnum
required
One or more permissions to revoke
​
return
$this
The role instance for method chaining
$role->revokePermissionTo('edit articles');
$role->revokePermissionTo(['edit articles', 'delete articles']);

​
checkPermissionTo

Check if the role has the given permission without throwing exceptions.
​
permission
string|int|Permission|BackedEnum
required
The permission to check
​
guardName
string|null
default:"null"
The guard name
​
return
bool
True if the role has the permission, false otherwise
if ($role->checkPermissionTo('edit articles')) {
    // Role has the permission
}

​
hasAnyPermission

Check if the role has any of the given permissions.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to check
​
return
bool
True if the role has at least one of the permissions
if ($role->hasAnyPermission(['edit articles', 'delete articles'])) {
    // Role has at least one of these permissions
}

if ($role->hasAnyPermission('edit articles', 'delete articles', 'publish articles')) {
    // Can also pass multiple arguments
}

​
hasAllPermissions

Check if the role has all of the given permissions.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to check
​
return
bool
True if the role has all of the permissions
if ($role->hasAllPermissions(['edit articles', 'delete articles'])) {
    // Role has both permissions
}

if ($role->hasAllPermissions('edit articles', 'delete articles', 'publish articles')) {
    // Can also pass multiple arguments
}

​
hasDirectPermission

Check if the role has the given permission directly assigned.
​
permission
string|int|Permission|BackedEnum
required
The permission to check
​
return
bool
True if the role has the permission directly
if ($role->hasDirectPermission('edit articles')) {
    // Role has this permission directly assigned
}

​
hasAllDirectPermissions

Check if the role has all of the given permissions directly assigned.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to check
​
return
bool
True if the role has all permissions directly
if ($role->hasAllDirectPermissions(['edit articles', 'delete articles'])) {
    // Role has both permissions directly assigned
}

​
hasAnyDirectPermission

Check if the role has any of the given permissions directly assigned.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to check
​
return
bool
True if the role has any permission directly
if ($role->hasAnyDirectPermission(['edit articles', 'delete articles'])) {
    // Role has at least one of these permissions directly
}

​
getAllPermissions

Get all permissions assigned to this role.
​
return
\Illuminate\Support\Collection
Collection of all permissions
$permissions = $role->getAllPermissions();

​
getPermissionNames

Get the names of all permissions assigned to this role.
​
return
\Illuminate\Support\Collection
Collection of permission names
$permissionNames = $role->getPermissionNames();
// ['edit articles', 'delete articles']

​
forgetCachedPermissions

Clear the permission cache. 
$role->forgetCachedPermissions();

​
Query Scopes

​
permission

Scope the query to roles that have certain permissions.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to filter by
$roles = Role::permission('edit articles')->get();
$roles = Role::permission(['edit articles', 'delete articles'])->get();

​
withoutPermission

Scope the query to roles that don’t have certain permissions.
​
permissions
string|int|array|Permission|Collection|BackedEnum
required
One or more permissions to exclude
$roles = Role::withoutPermission('delete articles')->get();

​
Team Support

When team support is enabled in the configuration, roles are automatically scoped to the current team. The package handles team filtering automatically in all queries and relationships. 
// With teams enabled, roles are automatically scoped
$role = Role::create([
    'name' => 'writer',
    'team_id' => 1
]);

​
Configuration

The Role model uses the following configuration options:
  • permission.table_names.roles - The database table name (default: roles)
  • permission.models.permission - The Permission model class to use for relationships
  • permission.table_names.role_has_permissions - The pivot table for role-permission relationships
  • permission.table_names.model_has_roles - The pivot table for user-role relationships
  • permission.teams - Enable team support
  • permission.teams_key - The foreign key column for team relationships

​
Events

The following events are fired when permissions are attached/detached:
  • Spatie\Permission\Events\PermissionAttachedEvent - Fired when a permission is granted
  • Spatie\Permission\Events\PermissionDetachedEvent - Fired when a permission is revoked

​
Wildcard Permissions

When wildcard permissions are enabled in the configuration, the hasPermissionTo method supports wildcard pattern matching: 
// If role has 'articles.*' permission
if ($role->hasPermissionTo('articles.edit')) {
    // This will return true due to wildcard matching
}
Wildcard permissions must be enabled in the configuration file.

Build docs developers (and LLMs) love

Get started for freeTalk to us