##Add The Trait
First, add the Spatie\Permission\Traits\HasRoles
trait to your User
model(s):
use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;
class User extends Authenticatable
{
use HasRoles;
}
##Create A Permission
This package allows for users to be associated with permissions and roles. Every role is associated with multiple permissions.
A Role
and a Permission
are regular Eloquent models. They require a name
and can be created like this:
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;
$role = Role::create(['name' => 'writer']);
$permission = Permission::create(['name' => 'edit articles']);
##Assign A Permission To A Role
A permission can be assigned to a role using either of these methods:
$role->givePermissionTo($permission);
$permission->assignRole($role);
##Sync Permissions To A Role
Multiple permissions can be synced to a role using either of these methods:
$role->syncPermissions($permissions);
$permission->syncRoles($roles);
##Remove Permission From A Role
A permission can be removed from a role using either of these methods:
$role->revokePermissionTo($permission);
$permission->removeRole($role);
##Guard Name
If you're using multiple guards then the guard_name
attribute must be set as well. Read about it in the using multiple guards section of the readme.
##Get Permissions For A User
The HasRoles
trait adds Eloquent relationships to your models, which can be accessed directly or used as a base query:
$permissionNames = $user->getPermissionNames();
$permissions = $user->permissions;
$permissions = $user->getDirectPermissions();
$permissions = $user->getPermissionsViaRoles();
$permissions = $user->getAllPermissions();
$roles = $user->getRoleNames();
##Scopes
The HasRoles
trait also adds role
and withoutRole
scopes to your models to scope the query to certain roles or permissions:
$users = User::role('writer')->get();
$nonEditors = User::withoutRole('editor')->get();
The role
and withoutRole
scopes can accept a string, a \Spatie\Permission\Models\Role
object or an \Illuminate\Support\Collection
object.
The same trait also adds scopes to only get users that have or don't have a certain permission.
$users = User::permission('edit articles')->get();
$usersWhoCannotEditArticles = User::withoutPermission('edit articles')->get();
The scope can accept a string, a \Spatie\Permission\Models\Permission
object or an \Illuminate\Support\Collection
object.
##Eloquent Calls
Since Role and Permission models are extended from Eloquent models, basic Eloquent calls can be used as well:
$allUsersWithAllTheirRoles = User::with('roles')->get();
$allUsersWithAllTheirDirectPermissions = User::with('permissions')->get();
$allRolesInDatabase = Role::all()->pluck('name');
$usersWithoutAnyRoles = User::doesntHave('roles')->get();
$allRolesExceptAandB = Role::whereNotIn('name', ['role A', 'role B'])->get();
##Counting Users Having A Role
One way to count all users who have a certain role is by filtering the collection of all Users with their Roles:
$superAdminCount = User::with('roles')->get()->filter(
fn ($user) => $user->roles->where('name', 'Super Admin')->toArray()
)->count();