Assigning Permissions

Once you’ve created permissions and roles, you can assign them to your users. Laravel Permission provides flexible methods for managing user permissions both directly and through roles.

Your User model must use the HasRoles trait to access these methods.

Assigning Roles to Users

Users can have multiple roles, and roles determine what permissions users have.

Assign Role
Remove Role
Sync Roles

Give one or more roles to a user:

use Spatie\Permission\Models\Role;

$user = User::find(1);

// Assign single role (string)
$user->assignRole('writer');

// Assign single role (Role model)
$role = Role::findByName('writer');
$user->assignRole($role);

// Assign multiple roles
$user->assignRole('writer', 'editor');
$user->assignRole(['writer', 'editor']);

If the user already has the role, it won’t be assigned again. The method is idempotent.

Revoke roles from a user:

// Remove single role
$user->removeRole('writer');

// Remove multiple roles
$user->removeRole('writer', 'editor');
$user->removeRole(['writer', 'editor']);

Replace all roles with a new set:

// Remove all existing roles and assign only these
$user->syncRoles(['writer', 'editor']);

// Remove all roles
$user->syncRoles([]);

syncRoles() removes ALL existing roles before assigning new ones.

Assigning Direct Permissions to Users

Besides inheriting permissions through roles, users can also have direct permissions.

Give Permission
Revoke Permission
Sync Permissions

Grant permissions directly to a user:

$user = User::find(1);

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

// Multiple permissions
$user->givePermissionTo('edit articles', 'delete articles');
$user->givePermissionTo(['edit articles', 'delete articles']);

// Using Permission model
$permission = Permission::findByName('edit articles');
$user->givePermissionTo($permission);

Direct permissions are useful for granting special access to specific users without creating a new role.

Remove direct permissions from a user:

// Revoke single permission
$user->revokePermissionTo('edit articles');

// This only removes DIRECT permissions
// If the user has the permission via a role, they'll still have access

Replace all direct permissions:

// Remove all direct permissions and assign only these
$user->syncPermissions(['edit articles', 'publish articles']);

// Remove all direct permissions
$user->syncPermissions([]);

This only affects direct permissions, not permissions inherited through roles.

Understanding Permission Sources

Users can have permissions from two sources:

Direct Permissions

Permissions assigned directly to the user:

// Get only direct permissions
$directPermissions = $user->permissions;
// or
$directPermissions = $user->getDirectPermissions();

Role Permissions

Permissions inherited from the user’s roles:

// Get permissions via roles
$rolePermissions = $user->getPermissionsViaRoles();

All Permissions

Combined permissions from both sources:

// Get all permissions (direct + via roles)
$allPermissions = $user->getAllPermissions();

Combining Roles and Direct Permissions

You can use both roles and direct permissions together:

$user = User::find(1);

// Assign a base role
$user->assignRole('writer');
// Now user has: 'edit articles' (via role)

// Grant additional direct permission
$user->givePermissionTo('publish articles');
// Now user has: 'edit articles' (via role) + 'publish articles' (direct)

Best Practice: Use roles for standard permissions and direct permissions for exceptions.Example: All writers can edit articles (via role), but only some writers can publish (via direct permission).

Method Signatures

Here are the key method signatures from the HasRoles trait:

public function assignRole(
    string|int|array|Role|Collection|BackedEnum ...$roles
): static

And from the HasPermissions trait:

public function givePermissionTo(
    string|int|array|Permission|Collection|BackedEnum ...$permissions
): static

Assigning During User Creation

You can assign roles and permissions when creating users:

$user = User::create([
    'name' => 'John Doe',
    'email' => '[email protected]',
    'password' => bcrypt('secret'),
]);

// Assign roles and permissions
$user->assignRole('writer');
$user->givePermissionTo('edit articles');

The user must be saved to the database before assigning roles or permissions. If you try to assign to an unsaved model, the assignments will be queued and applied when the model is saved.

Working with Multiple Guards

When using multiple authentication guards:

// User with web guard
$webUser = User::find(1);
$webUser->assignRole('admin'); // Assigns web guard role

// API user with api guard
$apiUser = ApiUser::find(1);
$apiUser->assignRole('admin'); // Assigns api guard role

// Explicitly specify guard
$user->assignRole(Role::findByName('admin', 'api'));

Roles and permissions must match the user’s guard. You’ll get a GuardDoesNotMatch exception if they don’t match.

Bulk Assignment

Assign roles and permissions to multiple users:

// Get multiple users
$users = User::whereIn('id', [1, 2, 3])->get();

// Assign same role to all
foreach ($users as $user) {
    $user->assignRole('writer');
}

// Or using query builder
User::whereIn('id', [1, 2, 3])
    ->each(fn($user) => $user->assignRole('writer'));

Event Handling

Laravel Permission fires events when roles and permissions are assigned:

use Spatie\Permission\Events\RoleAttachedEvent;
use Spatie\Permission\Events\PermissionAttachedEvent;

// Listen for role assignments
Event::listen(RoleAttachedEvent::class, function ($event) {
    $model = $event->model; // The user
    $roleIds = $event->roleIds; // Array of role IDs
});

// Listen for permission assignments
Event::listen(PermissionAttachedEvent::class, function ($event) {
    $model = $event->model; // The user
    $permissionIds = $event->permissionIds; // Array of permission IDs
});

Events are only fired if permission.events_enabled is set to true in your config.

Common Patterns

New User Default Role

Automatically assign a role to new users:

// In User model
protected static function booted()
{
    static::created(function ($user) {
        $user->assignRole('user');
    });
}

Promotion/Demotion

Change user roles based on actions:

public function promoteToEditor(User $user)
{
    $user->removeRole('writer');
    $user->assignRole('editor');
}

public function demoteToWriter(User $user)
{
    $user->removeRole('editor');
    $user->assignRole('writer');
}

Temporary Permissions

Grant temporary additional permissions:

// Grant extra permission for specific task
$user->givePermissionTo('delete articles');

// Perform task
$article->delete();

// Revoke the permission
$user->revokePermissionTo('delete articles');

Getting Started

Basic Usage

Advanced Usage

Configuration

Best Practices

Additional Resources

Assigning Roles to Users

Assigning Direct Permissions to Users

Understanding Permission Sources

Combining Roles and Direct Permissions

Method Signatures

Assigning During User Creation

Working with Multiple Guards

Bulk Assignment

Event Handling

Common Patterns

Next Steps

Checking Permissions

Blade Directives

Build docs developers (and LLMs) love

Getting Started

Basic Usage

Advanced Usage

Configuration

Best Practices

Additional Resources

​Assigning Roles to Users

​Assigning Direct Permissions to Users

​Understanding Permission Sources

​Combining Roles and Direct Permissions

​Method Signatures

​Assigning During User Creation

​Working with Multiple Guards

​Bulk Assignment

​Event Handling

​Common Patterns

​Next Steps

Checking Permissions

Blade Directives

Build docs developers (and LLMs) love

Assigning Roles to Users

Assigning Direct Permissions to Users

Understanding Permission Sources

Combining Roles and Direct Permissions

Method Signatures

Assigning During User Creation

Working with Multiple Guards

Bulk Assignment

Event Handling

Common Patterns

Next Steps