Skip to main content
Roles are a way to group permissions together. A user can have multiple roles, and each role can have multiple permissions.

​
Creating Roles

Roles can be created in several ways, similar to permissions.
The standard way to create a role:
use Spatie\Permission\Models\Role;

$role = Role::create(['name' => 'writer']);
Like permissions, the guard_name defaults to your application’s default guard.

​
Finding Roles

Retrieve existing roles using various lookup methods.
1

Find by Name

Look up a role by its name:
$role = Role::findByName('writer');

// With specific guard
$role = Role::findByName('admin', 'api');
Throws RoleDoesNotExist exception if the role is not found.
2

Find by ID

Retrieve a role by its database ID:
$role = Role::findById(1);

// With specific guard
$role = Role::findById(1, 'api');
3

Find or Create

Safe method that never throws exceptions:
$role = Role::findOrCreate('moderator');

​
Role Properties

Each role model has the following properties:
PropertyTypeDescription
idint|stringPrimary key
namestringRole name (e.g., ‘writer’, ‘admin’)
guard_namestringAuthentication guard
created_atCarbonCreation timestamp
updated_atCarbonLast update timestamp

​
Assigning Permissions to Roles

Roles can have multiple permissions assigned to them.
Assign one or more permissions to a role:
$role = Role::findByName('writer');

// Single permission
$role->givePermissionTo('edit articles');

// Multiple permissions
$role->givePermissionTo('edit articles', 'delete articles');

// Using permission models
$role->givePermissionTo($permission);

​
Checking Role Permissions

Verify if a role has specific permissions: 
$role = Role::findByName('writer');

// Check if role has a permission
if ($role->hasPermissionTo('edit articles')) {
    // Role has the permission
}
The method signature from HasPermissions trait:
public function hasPermissionTo(
    string|int|Permission|BackedEnum $permission, 
    ?string $guardName = null
): bool

​
Retrieving Role Permissions

Get all permissions assigned to a role: 
$role = Role::findByName('writer');

// Get all permissions as a collection
$permissions = $role->permissions;

// Get permission names only
$permissionNames = $role->permissions->pluck('name');
// Example output: ['edit articles', 'publish articles']

// Count permissions
$count = $role->permissions()->count();

​
Role Relationships

​
Permissions Relationship

Access the role’s permissions: 
$role = Role::findByName('writer');

// Eager load permissions
$role->load('permissions');

// Query permissions
$articlePermissions = $role->permissions()
    ->where('name', 'like', '%article%')
    ->get();

​
Users Relationship

Access users who have this role: 
$role = Role::findByName('admin');

// Get all users with this role
$admins = $role->users;

// Count users with this role
$adminCount = $role->users()->count();

// Query users
$activeAdmins = $role->users()
    ->where('active', true)
    ->get();

​
Deleting Roles

Remove roles from the database: 
$role = Role::findByName('writer');
$role->delete();
When you delete a role:
  • It’s automatically detached from all users
  • The permission cache is cleared
  • The permissions assigned to the role are NOT deleted (only the role-permission relationships)

​
Common Role Patterns

A simple role hierarchy for a blog:
// Create roles
$reader = Role::create(['name' => 'reader']);
$writer = Role::create(['name' => 'writer']);
$editor = Role::create(['name' => 'editor']);
$admin = Role::create(['name' => 'admin']);

// Reader can only view
$reader->givePermissionTo('view articles');

// Writer can view and edit
$writer->givePermissionTo('view articles', 'edit articles');

// Editor can view, edit, and publish
$editor->givePermissionTo('view articles', 'edit articles', 'publish articles');

// Admin can do everything
$admin->givePermissionTo('view articles', 'edit articles', 'publish articles', 'delete articles');

​
Best Practices

Role Naming: Use descriptive, lowercase names with hyphens:
  • Good: super-admin, content-editor, customer-support
  • Avoid: SuperAdmin, EDITOR, Support_Agent
Role Seeders: Create roles in database seeders:
// database/seeders/RoleSeeder.php
public function run()
{
    // Create roles
    $admin = Role::findOrCreate('admin');
    $editor = Role::findOrCreate('editor');
    $writer = Role::findOrCreate('writer');

    // Assign permissions
    $admin->syncPermissions(['edit articles', 'delete articles', 'publish articles']);
    $editor->syncPermissions(['edit articles', 'publish articles']);
    $writer->syncPermissions(['edit articles']);
}
Keep Roles Simple: Don’t create too many roles. Instead:
  • Use a few broad roles with different permissions
  • Combine roles on users when needed
  • Use direct permission assignment for exceptions

​
Guard-Specific Roles

When using multiple authentication guards: 
// Web guard (regular users)
$webAdmin = Role::create(['name' => 'admin', 'guard_name' => 'web']);

// API guard (API clients)
$apiAdmin = Role::create(['name' => 'admin', 'guard_name' => 'api']);

// These are treated as completely separate roles
Roles with the same name but different guards are independent entities.

​
Next Steps

Assigning Permissions

Learn how to assign roles and permissions to users

Checking Permissions

Check if users have permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us