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.

Roles List

Permissions Interface

You can find the permissions section inside Admin -> Access Control -> Permissions.
Feel free to explore all available options this section offers.

Roles List

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:

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.