Roles & Permissions
This functionality allows you to manage roles & permissions for your users.
The Varbox platform comes out of the box with a solution for role based permissions already integrated on your App\User
model.
If you want to attach the role based permission functionality on other models, all you have to do is use the Varbox\Traits\HasRolesAndPermissions
trait on your models.
<?php
namespace App;
use Illuminate\Database\Eloquent\Model;
use Varbox\Traits\HasRolesAndPermissions;
class YourModel extends Model
{
use HasRolesAndPermissions;
}
Admin Interface
Before going deeper, you should know that there's already a section in the admin from where you can manage all your roles and permissions.
Roles Interface
You can find the roles section inside Admin -> Access Control -> Roles.
Feel free to explore all available options this section offers.
Permissions Interface
You can find the permissions section inside Admin -> Access Control -> Permissions.
Feel free to explore all available options this section offers.
Manage Access
The Varbox admin panel already supports role based permissions for the logged in user.
Role Based Access
You can restrict access to users based on their roles by using the varbox.check.roles
middleware.
Route::get('your-url')->name('your-name')
->middleware('varbox.check.roles:role_1,role_2');
You can even specify the middleware at route group
level and then pass a roles
parameter to individual routes.
Route::group([
'middleware' => 'varbox.check.roles'
], funnction () {
Route::get('your-url-1', ['roles' => 'role_1']);
Route::get('your-url-2', ['roles' => 'role_2']);
});
Permission Based Access
You can restrict access to users based on their permissions by using the varbox.check.permissions
middleware.
Route::get('your-url')->name('your-name')
->middleware('varbox.check.permissions:permission_1,permission_2');
You can even specify the middleware at route group
level and then pass a permissions
parameter to individual routes.
Route::group([
'middleware' => 'varbox.check.permissions'
], funnction () {
Route::get('your-url-1', ['permissions' => 'permission_1']);
Route::get('your-url-2', ['permissions' => 'permission_2']);
});
Roles Usage
When working with your App\User
model you have a few options when it comes to managing your roles.
Fetch Roles
You can get a user's assigned roles, by using the roles()
many to many relation.
$roles = $user->roles;
Save Roles
You can assign one or multiple roles to a user by using the assignRoles()
method.
// by role name
$user->assignRoles('owner');
// by array
$user->assignRoles(['owner', 'editor']);
// by collection
$user->assignRoles(Role::all());
You can remove one or multiple roles from a user by using the removeRoles()
method.
// by role name
$user->removeRoles('owner');
// by array
$user->removeRoles(['owner', 'editor']);
// by collection
$user->removeRoles(Role::all());
You can sync the roles for a user by using the syncRoles()
method.
This method detaches all assigned roles and then it assigns
the specified roles for the user.
// by role name
$user->syncRoles('owner');
// by array
$user->syncRoles(['owner', 'editor']);
// by collection
$user->syncRoles(Role::all());
Query By Roles
You can get users that have certain roles by using the withRoles
query scope.
// by role name
$users = User::withRoles('owner')->get();
// by array
$users = User::withRoles(['owner', 'editor'])->get();
// by collection
$users = User::withRoles(Role::all())->get();
You can get users that don't have certain roles by using the withoutRoles
query scope.
// by role name
$users = User::withoutRoles('owner')->get();
// by array
$users = User::withoutRoles(['owner', 'editor'])->get();
// by collection
$users = User::withoutRoles(Role::all())->get();
Check For Roles
You can check if a user has a certain role by using the hasRole()
method.
$user->hasRole('owner');
You can check if a user has at least one of the specified roles by using the hasAnyRole()
method.
$user->hasAnyRole(['owner', 'editor']);
You can check if a user has all of the specified roles by using the hasAllRoles()
method.
$user->hasAllRoles(['owner', 'editor']);
Permissions Usage
When working with your App\User
model you have a few options when it comes to managing your permissions.
Fetch Permissions
You can get a user's assigned permissions, by using the permissions()
many to many relation.
$permissions = $user->permissions;
Save Permissions
You can grant one or multiple permissions to a user by using the grantPermission()
method.
// by permission name
$user->grantPermission('view-users');
// by array
$user->grantPermission(['view-users', 'edit-users']);
// by collection
$user->grantPermission(Permission::all());
You can revoke one or multiple permissions from a user by using the revokePermission()
method.
// by peermission name
$user->revokePermission('view-users');
// by array
$user->revokePermission(['view-users', 'edit-users']);
// by collection
$user->revokePermission(Permission::all());
You can sync the permissions for a user by using the syncPermissions()
method.
This method detaches all assigned permissions and then it grants
the specified permissions for the user.
// by permission name
$user->syncPermissions('view-users');
// by array
$user->syncPermissions(['view-users', 'editor']);
// by collection
$user->syncPermissions(Permission::all());
Query By Permissions
You can get users that have certain permissions by using the withPermissions
query scope.
// by permission name
$users = User::withPermissions('view-users')->get();
// by array
$users = User::withPermissions(['view-users', 'edit-users'])->get();
// by collection
$users = User::withPermissions(Role::all())->get();
You can get users that don't have certain permissions by using the withoutPermissions
query scope.
// by permission name
$users = User::withoutPermissions('view-users')->get();
// by array
$users = User::withoutPermissions(['view-users', 'edit-users'])->get();
// by collection
$users = User::withoutPermissions(Role::all())->get();
Check For Permissions
You can check if a user has a certain permission by using the hasPermission()
method.
$user->hasPermission('view-users');
You can check if a user has at least one of the specified permissions by using the hasAnyPermission()
method.
$user->hasAnyPermission(['view-users', 'edit-users']);
You can check if a user has all of the specified permissions by using the hasAllPermissions()
method.
$user->hasAllPermissions(['view-users', 'edit-users']);
Seeder Classes
The Varbox platform publishes a few seeder classes inside you database/seeds
directory.
Roles Seeder
The database/seeds/RolesSeeder.php
is your seeder class for roles.
To add a new role to the seeder, just append your role to the $roles
property:
/**
* Mapping structure of admin roles.
*
* @var array
*/
protected $roles = [
...
'Editor' => [
'name' => 'Editor',
'guard' => 'admin',
],
];
Then simply seed your roles by running the following artisan command:
php artisan db:seed --class="RolesSeeeder"
When running the seeder, a check is performed for each role to verify if it already exists, so you won't end up with duplicated roles on subsequential executions of the seeder.
By default, the following roles are already present for you to use:
Admin
- a user having this role will be able to access the admin panelSuper
- a user having this role will have full access inside the admin panel
Permissions Seeder
The database/seeds/PermissionsSeeder.php
is your seeder class for permissions.
To add new permissions to the seeder, just append your permissions to the $permissions
property:
/**
* Mapping structure of admin permissions.
*
* @var array
*/
protected $permissions = [
...
'Posts' => [
'List' => [
'group' => 'Posts',
'label' => 'List',
'guard' => 'admin',
'name' => 'posts-list',
],
'Add' => [
'group' => 'Posts',
'label' => 'Add',
'guard' => 'admin',
'name' => 'posts-add',
],
'Edit' => [
'group' => 'Posts',
'label' => 'Edit',
'guard' => 'admin',
'name' => 'posts-edit',
],
'Delete' => [
'group' => 'Posts',
'label' => 'Delete',
'guard' => 'admin',
'name' => 'posts-delete',
],
],
];
Then simply seed your permissions by running the following artisan command:
php artisan db:seed --class="PermissionsSeeeder"
When running the seeder, a check is performed for each permission to verify if it already exists, so you won't end up with duplicated permissions on subsequential executions of the seeder.
By default, all necessary permissions for each platform specific functionality are already seeded.
Overwrite Bindings
In your projects, you may stumble upon the need to modify the behavior of these classes, in order to fit your needs.
Varbox makes this possible via the config/varbox/bindings.php
configuration file. In that file, you'll find every customizable class the platform uses.
For more information on how the class binding works, please refer to the Custom Bindings documentation section.
Varbox\Models\Role
Found in config/varbox/bindings.php
at models.role_model
key.
This class represents the role model.
Varbox\Models\Permission
Found in config/varbox/bindings.php
at models.permission_model
key.
This class represents the permission model.
Varbox\Controllers\RolesController
Found in config/varbox/bindings.php
at controllers.roles_controller
key.
This class is used for interactions with the "Admin -> Access Control -> Roles" section.
Varbox\Controllers\PermissionsController
Found in config/varbox/bindings.php
at controllers.permissions_controller
key.
This class is used for interactions with the "Admin -> Access Control -> Permissions" section.
Varbox\Requests\RoleRequest
Found in config/varbox/bindings.php
at form_requests.role_form_request
key.
This class is used for validating any role when inserting into the database.
Varbox\Requests\PermissionRequest
Found in config/varbox/bindings.php
at form_requests.permission_form_request
key.
This class is used for validating any permission when inserting into the database.
Varbox\Middleware\CheckRoles
Found in config/varbox/bindings.php
at middleware.check_roles_middleware
key.
This class is used for restricting access to users based on the given roles.
Varbox\Middleware\CheckPermissions
Found in config/varbox/bindings.php
at middleware.check_permissions_middleware
key.
This class is used for restricting access to users based on the given permissions.
Varbox\Filters\PermissionFilter
Found in config/varbox/bindings.php
at filters.permission_filter
key.
This class is used for applying the filtering logic.
Varbox\Filters\RoleFilter
Found in config/varbox/bindings.php
at filters.role_filter
key.
This class is used for applying the filtering logic.
Varbox\Sorts\PermissionSort
Found in config/varbox/bindings.php
at sorts.permission_sort
key.
This class is used for applying the sorting logic.
Varbox\Sorts\RoleSort
Found in config/varbox/bindings.php
at sorts.role_sort
key.
This class is used for applying the sorting logic.