Skip to content
YajraBox

Laravel Acl

Permission Role

Quick Summary: The InteractsWithRole trait provides easy-to-use methods to manage and assign roles to any model.

Getting Started

All methods are available on any model that uses the InteractsWithRole trait:

use App\Models\User;
use Yajra\Acl\Traits\InteractsWithRole;
 
class User extends Model
{
    use InteractsWithRole;
}

Checking Roles

hasRole($role)

Check if the user has the given role.

Parameters:

Parameter Type Description
$role string | array<string> | BackedEnum | UnitEnum Role slug(s) or enum to check

[!TIP] Returns true if the user has any of the roles when using an array.

Examples:

$user = User::find(1);
 
// Single role check
if ($user->hasRole('admin')) {
    // User is an admin
}
 
// Multiple roles (OR logic - true if user has ANY of the roles)
if ($user->hasRole(['admin', 'editor'])) {
    // User is an admin OR editor
}
 
// Using enums
enum RoleEnum: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}
 
if ($user->hasRole(RoleEnum::Admin)) {
    // User is an admin
}

getRoleSlugs()

Get all role slugs assigned to the user.

Returns: Array of role slugs.

Example:

$user = User::find(1);
 
$slugs = $user->getRoleSlugs();
// ['admin', 'editor', 'moderator']

Attaching Roles

attachRole($role, $attributes, $touch)

Attach a role to the user.

Parameters:

Parameter Type Default Description
$role mixed — Role model instance, role slug (string), or enum
$attributes array [] Pivot table attributes (e.g., ['expires_at' => now()->addMonth()])
$touch bool true Whether to touch the model's timestamps

Examples:

$user = User::find(1);
 
// Attach by role model
$role = Role::find(1);
$user->attachRole($role);
 
// Attach by slug
$user->attachRole('admin');
 
// Attach by enum
enum RoleEnum: string
{
    case Admin = 'admin';
}
 
$user->attachRole(RoleEnum::Admin);
 
// Attach with pivot attributes
$user->attachRole('admin', ['expires_at' => now()->addMonth()]);

attachRoleBySlug($slug)

Attach a role using only the role slug (alias for attachRole($slug)).

Parameters:

Parameter Type Description
$slug string Role slug to attach

Example:

$user = User::find(1);
$user->attachRoleBySlug('admin');

Revoking Roles

revokeRole($role, $touch)

Revoke a role from the user.

Parameters:

Parameter Type Default Description
$role mixed — Role model instance, role slug (string), or enum
$touch bool true Whether to touch the model's timestamps

[!NOTE] Returns the number of roles detached.

Examples:

$user = User::find(1);
 
// Revoke by role model
$role = Role::find(1);
$detached = $user->revokeRole($role);
 
// Revoke by slug
$detached = $user->revokeRole('admin');
 
// Revoke by enum
enum RoleEnum: string
{
    case Admin = 'admin';
}
 
$detached = $user->revokeRole(RoleEnum::Admin);

revokeRoleBySlug($slug, $touch)

Revoke a role using the role slug.

Parameters:

Parameter Type Default Description
$slug string | array<string> — Role slug(s) to revoke
$touch bool true Whether to touch the model's timestamps

Examples:

$user = User::find(1);
 
// Revoke a single role
$detached = $user->revokeRoleBySlug('admin');
 
// Revoke multiple roles at once
$detached = $user->revokeRoleBySlug(['admin', 'editor']);

revokeAllRoles()

Revoke all roles from the user.

Returns: Number of roles detached.

Example:

$user = User::find(1);
 
$detached = $user->revokeAllRoles();

Syncing Roles

syncRoles($roles, $detaching)

Sync the user's roles. Replaces all current roles with the given roles.

Parameters:

Parameter Type Default Description
$roles Collection | Model | array<int> — Role(s) to sync (IDs or model instances)
$detaching bool true Whether to detach roles not in the given list

[!TIP] Returns ['attached' => [], 'detached' => [], 'updated' => []] with role IDs.

Examples:

$user = User::find(1);
 
// Sync with role IDs
$result = $user->syncRoles([1, 2, 3]);
// ['attached' => [1, 2, 3], 'detached' => [], 'updated' => []]
 
// Sync with role models
$roles = Role::whereIn('slug', ['admin', 'editor'])->get();
$result = $user->syncRoles($roles);
 
// Sync without detaching (keeps existing roles)
$result = $user->syncRoles([1, 2], detaching: false);

Query Scopes

The InteractsWithRole trait provides query scopes for filtering models by their roles.

scopeHavingRoles($roles)

Filter records that have the specified roles.

Parameters:

Parameter Type Description
$roles array<int | string | BackedEnum | UnitEnum | Model> Role IDs, slugs, enums, or model instances

Examples:

// Filter by role ID
$users = User::havingRoles([1, 2])->get();
 
// Filter by role slugs
$users = User::havingRoles(['admin', 'editor'])->get();
 
// Filter by enums
enum RoleEnum: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}
 
$users = User::havingRoles([RoleEnum::Admin, RoleEnum::Editor])->get();
 
// Filter by role models
$roles = Role::where('slug', 'admin')->get();
$users = User::havingRoles($roles)->get();
 
// Mixed filter
$users = User::havingRoles([
    1,                          // Role ID
    'admin',                   // Role slug
    RoleEnum::Editor,          // Enum
    Role::find(2),             // Role model
])->get();

scopeHavingRolesBySlugs($slugs)

Filter records by role slugs.

Parameters:

Parameter Type Description
$slugs array<string> Array of role slugs

Example:

$users = User::havingRolesBySlugs(['admin', 'editor'])->get();

Enum Support

[!INFO] All methods that accept a role parameter support enums out of the box.

Supported Enum Types

Enum Type Value Used Example
BackedEnum ->value RoleEnum::Admin->value = 'admin'
UnitEnum ->name PermissionLevel::Admin->name = 'Admin'

Examples:

// BackedEnum - Uses the enum's value
enum RoleEnum: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}
 
// UnitEnum - Uses the enum's name
enum PermissionLevel
{
    case Read;
    case Write;
    case Admin;
}
 
$user = User::find(1);
 
// All valid usages:
$user->hasRole(RoleEnum::Admin);           // valid
$user->hasRole(PermissionLevel::Admin);   // valid
$user->attachRole(RoleEnum::Editor);       // valid
$user->revokeRole(PermissionLevel::Write); // valid

Quick Reference

[!TIP] Bookmark this section for a quick overview!

Method Signatures

// Checking Roles
hasRole(string|array|BackedEnum|UnitEnum $role): bool
getRoleSlugs(): array
 
// Attaching Roles
attachRole(mixed $role, array $attributes = [], bool $touch = true): void
attachRoleBySlug(string $slug): void
 
// Revoking Roles
revokeRole(mixed $role, bool $touch = true): int
revokeRoleBySlug(string|array $slug, bool $touch = true): int
revokeAllRoles(): int
 
// Syncing Roles
syncRoles(Collection|Model|array $roles, bool $detaching = true): array
 
// Query Scopes
scopeHavingRoles(Builder $query, array $roles): Builder
scopeHavingRolesBySlugs(Builder $query, array $slugs): Builder
Edit this page on GitHub