Roles

The HasRoles trait also adds a havingRole scope to your models to scope the query to certain roles:

$users = User::havingRole('writer')->get(); // Returns only users with the role 'writer'

The havingRoles scope allows querying for multiple roles:

$users = User::havingRoles('writer', 'editor', 'supervisor')->get(); // Returns the users that have at least one of the given roles

Permissions via Roles

A role can be assigned to any user:

$user->assignRole('writer');

// You can also assign multiple roles at once
$user->assignRole('writer', 'admin');

A role can be removed from a user:

$user->removeRole('writer');

Roles can also be synced:

// All current roles will be removed from the user and replaced by the array given
$user->syncRoles('writer', 'admin');

You can determine if a user has a certain role:

$user->hasRole('writer');

You can also determine if a user has any of a given list of roles:

$user->hasAnyRole(Role::all());

You can also determine if a user has all of a given list of roles:

$user->hasAllRoles(Role::all());

A permission can be given to a role:

$role->givePermissionTo('edit articles');

You can determine if a role has a certain permission:

$role->hasPermissionTo('edit articles');

A permission can be revoked from a role:

$role->revokePermissionTo('edit articles');

The givePermissionTo and revokePermissionTo functions can accept a string or a Permission object.

Permissions are inherited from roles automatically. Additionally, individual permissions can be assigned to the user too.

For instance:

$role = Role::findByName('writer');
$role->givePermissionTo('edit articles');

$user->assignRole('writer');

$user->givePermissionTo('delete articles');

In the above example, a role is given permission to edit articles and this role is assigned to a user.

Now the user can edit articles and additionally delete articles. The permission of 'delete articles' is the user's direct permission because it is assigned directly to them.

When we call $user->hasDirectPermission('delete articles') it returns true, but false for $user->hasDirectPermission('edit articles').

This method is useful if one builds a form for setting permissions for roles and users in an application and wants to restrict or change inherited permissions of roles of the user, i.e. allowing to change only direct permissions of the user.

You can list all of these permissions:

// Direct permissions
$user->getDirectPermissions(); // Or $user->permissions;

// Permissions inherited from the user's roles
$user->getPermissionsViaRoles();

// All permissions which apply on the user (inherited and direct)
$user->getAllPermissions();

All these responses are collections of Permission objects.

If we follow the previous example, the first response will be a collection with the 'delete article' permission, the second will be a collection with the 'edit article' permission and the third will contain both.

If we follow the previous example, the first response will be a collection with the delete article permission and the second will be a collection with the edit article permission and the third will contain both.

Next: Blade Directives »