Roles
Roles are the responsible for grouping granted permissions. A role has be assigned to one or more users and thereby granting the users whatever permissions are granted to the role itself.
Creating a new role
To create a new role, you can use the static create()
method, as you normally would in your Eloquent model.
use Aedart\Acl\Models\Role;
$manager = Role::create([
'slug' => 'flight-manager',
'name' => 'Flight manager',
'description' => 'Responsible for managing flight records'
]);
See Laravel's documentation for additional information on how to create new records.
New role with permissions
If you already know which permissions a new role should be granted, then you can define these right away, during the role's creation. This is done so, via the createWithPermissions()
method.
use Aedart\Acl\Models\Permissions\Group;
use Aedart\Acl\Models\Role;
$permissions = Group::findBySlug('flights')->permissions;
$manager = Role::create([
'slug' => 'flight-manager',
'name' => 'Flight manager',
'description' => 'Responsible for managing flight records'
], $permissions);
Grant permissions
The grantPermissions()
method allows you to grant one or more permissions to the given role. The method can accept multiple types of permission identifiers:
string
: permission's unique slugint
: permissions unique id (integer)Permission
: instance of Permission modelCollection
: a collection of permission modelsarray
: list of permission slugs, ids or models
$role = Role::findBySlug('flight-manager');
$role->grantPermissions($permissions);
// ... Or via array...
$role->grantPermissions([ 'flights.index', 'flights.show', 'flights.store' ]);
// ... Or single permission via slug
$role->grantPermissions('flights.destroy');
Revoke permissions
To revoke permissions from an existing role, use the revokePermissions()
method. It accepts the same type of arguments as the grantPermissions()
method.
$role->revokePermissions([ 'flights.update', 'flights.destroy' ]);
Revoking all permissions
Use the revokeAllPermissions()
method to revoke all permissions for given role.
$role->revokeAllPermissions();
Synchronise permissions
If you require synchronising granted permissions, then use the syncPermissions()
method.
// Regardless of what permissions previously were granted,
// the role will now only be granted the given permissions...
$role->syncPermissions([
'flights.index',
'flights.show',
'flights.store',
]);
For additional information about relations synchronisation, please review Laravel's documentation.
Update role with permissions
To update a role's attributes and also grant it permissions, use the updateAndGrantPermissions()
method.
$permissions = [ 'flights.index', 'flights.show' ];
$role = Role::findBySlug('flight-manager');
$role->updateAndGrantPermissions([
'description' => 'Responsible for supervising flight records'
], $permissions);
Update and synchronise permissions
Alternatively, you may also synchronise permissions when updating an existing role.
$permissions = [ 'flights.index', 'flights.show' ];
$role = Role::findBySlug('flight-manager');
$role->updateAndSyncPermissions([
'description' => 'Responsible for supervising flight records'
], $permissions);
Check role's permissions
When you need to determine whether a role has specific permissions or not, then the following methods can be used.
Has permission
The hasPermission()
method returns true
, if given permission are granted to the role.
echo $role->hasPermission('flights.update'); // e.g. false (0)
Has all permissions
To determine if a role has multiple permissions granted, use the hasAllPermissions()
. The method only returns true
, if all given permissions are granted.
echo $role->hasAllPermissions([ 'flights.destroy', 'flights.store' ]); // e.g. true (1)
Has any permissions
Lastly, to determine if a role has either (one of) of given permissions, use the hasAnyPermissions()
method.
// Returns true if either permission is granted
echo $role->hasAnyPermissions([ 'flights.index', 'flights.show' ]); // e.g. true (1)