andrey-helldar/laravel-roles

This package is abandoned and no longer maintained. The author suggests using the spatie/laravel-permission package instead.

Simple roles and permissions handling for Laravel

v2.7.1 2020-07-14 15:01 UTC

README

Basic roles and permissions handling for Laravel 5.5 and up.

laravel roles

This package is abandoned and no longer maintained. The author suggests using the spatie/laravel-permission package instead.

StyleCI Status Github Workflow Status Coverage Status Scrutinizer Code Quality For Laravel

Stable Version Unstable Version Total Downloads License

Contents

Installation

If you upgrade from the old version, you can see the list of changes in the Upgrade Guide:

To get the latest version of Laravel Roles, simply require the project using Composer:

$ composer require andrey-helldar/laravel-roles

Or manually update require block of composer.json and run composer update.

{
    "require-dev": {
        "andrey-helldar/laravel-roles": "^2.4"
    }
}

Now you can publish the configuration and migration file by running the command:

php artisan vendor:publish --provider="Helldar\Roles\ServiceProvider"

You can create the DB tables by running the migrations:

php artisan migrate

This command will create such roles, permissions, user_role and role_permission tables.

Using

User model

First, add the Helldar\Roles\Traits\HasRoles trait to your User model:

use Illuminate\Foundation\Auth\User as Authenticatable;
use Helldar\Roles\Traits\HasRoles;

class User extends Authenticatable
{
    use HasRoles;

    // ...
}

Middleware

You can add middlewares in $routeMiddleware of app/Http/Kernel.php file:

use Helldar\Roles\Http\Middleware\Permission;
use Helldar\Roles\Http\Middleware\Permissions;
use Helldar\Roles\Http\Middleware\Role;
use Helldar\Roles\Http\Middleware\Roles;

protected $routeMiddleware = [
    // ...
    
    'role'        => Role::class,        // Checks for the entry of one of the specified permissions.
    'roles'       => Roles::class,       // Checks the entry of all of the specified permissions.
    'permission'  => Permission::class,  // Checks for the occurrence of one of the specified roles.
    'permissions' => Permissions::class, // Checks the entry of all of the specified roles.
]

Now you can check if one of the conditions is met:

// Example, user has been a `foo` role and a `baz` permission

// success access
app('router')
    ->middleware('role:foo,bar', 'permission:foo,bar')
    ->get(...)

// success access
app('router')
    ->middleware('role:foo,bar')
    ->get(...)

// failed access
app('router')
    ->middleware('permission:foo,bar')
    ->get(...)

Or check the entry of all conditions:

// Example, user has been a `foo` role and a `baz` permission

// failed access
app('router')
    ->middleware('roles:foo,bar', 'permissions:foo,bar')
    ->get(...)

// failed access
app('router')
    ->middleware('roles:foo,bar')
    ->get(...)

// success access
app('router')
    ->middleware('roles:foo')
    ->get(...)

// failed access
app('router')
    ->middleware('permissions:foo,bar')
    ->get(...)

// success access
app('router')
    ->middleware('permissions:baz')
    ->get(...)

Creating

use Helldar\Roles\Models\Role;
use Helldar\Roles\Models\Permission;

$role = Role::create(['slug' => 'admin']);
$permission = Permission::create(['slug' => 'update']);

$role->assignPermission($permission);

// or

$user = User::find(1);

$role = $user->createRole('Mega Admin'); // creating Role instance with "mega_admin" slug and "Mega_Admin" title.
$role = $user->createRole('Mega Admin', 'Mega Admin'); // creating Role instance with "mega_admin" slug and "Mega Admin" title.
$role = $user->createRole('Mega Admin', 'Mega Admin', true); // creating Role instance with "mega_admin" slug and "Mega Admin" title and `is_root` role.

$role->createPermission('Post edit'); // creating Permission instance with "post_edit" slug and "Post_Edit" title.
$role->createPermission('Post edit', 'Post edit'); // creating Permission instance with "post_edit" slug and "Post edit" title.

Assign, revoke and sync permissions

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.

Assign permissions

To add roles and permissions, use the following methods:

use \Helldar\Roles\Models\Role;
use \Helldar\Roles\Models\Permission;

// For User
$user->assignRole('role_slug');
$user->assignRole(Role::find(1));
$user->assignRole(1);

$user->assignRoles($role_1, 'role_slug_2', 3, ...);

// Adds to the user the role specified in the `default_role`
// parameter of the `config/roles.php` file.
// If `null`, then no addition will be made.
$user->assignDefaultRole();

$user->assignPermission('permission_slug');
$user->assignPermission(Permission::find(1));
$user->assignPermission(1);

$user->assignPermissions($permission_1, 'permission_2', 3, ...);


// For Role
use \Helldar\Roles\Models\Permission;

$role->assignPermission('permission_slug');
$role->assignPermission(Permission::find(1));
$role->assignPermission(1);

$role->assignPermissions($permission_1, 'permission_2', 3, ...);


// For Permission
use \Helldar\Roles\Models\Role;

$permission->assignRole('role_slug');
$permission->assignRole(Role::find(1));
$permission->assignRole(1);

$permission->assignRoles($role_1, 'role_2', 3, ...);

Revoke permissions

To revoke roles and permissions, use the following methods:

use \Helldar\Roles\Models\Role;
use \Helldar\Roles\Models\Permission;

// For User
$user->revokeRole('role_slug');
$user->revokeRole(Role::find(1));
$user->revokeRole(1);

$user->revokeRoles($role_1, 'role_slug_2', 3, ...);

$user->revokePermission('permission_slug');
$user->revokePermission(Permission::find(1));
$user->revokePermission(1);

$user->revokePermissions($permission_1, 'permission_2', 3, ...);


// For Role
use \Helldar\Roles\Models\Permission;

$role->revokePermission('permission_slug');
$role->revokePermission(Permission::find(1));
$role->revokePermission(1);

$role->revokePermissions($permission_1, 'permission_2', 3, ...);


// For Permission
use \Helldar\Roles\Models\Role;

$permission->revokeRole('role_slug');
$permission->revokeRole(Role::find(1));
$permission->revokeRole(1);

$permission->revokeRoles($role_1, 'role_2', 3, ...);

Syncing permissions

To synchronization roles and permissions, use the following methods:

// For User
$user->syncRoles([1, 2, 3, ...]);
$user->syncPermissions([1, 2, 3, ...]);


// For Role
$role->syncPermissions([1, 2, 3, ...]);


// For Permission
$permission->syncRoles([1, 2, 3, ...]);

Blade

If you enabled the use of directives in the config file, you can still using can() blade directive with additional role() and permission() directives:

@can('permission_slug')
    I can see this text
@endcan

@if(auth()->user()->can('permission_slug'))
    I can see this text
@endif


@role('role_slug')
    I can see this text
@endrole

@role(auth()->user()->hasRole('role_slug'))
    I can see this text
@endrole


@roles('role_slug_1', 'role_slug_2', 'role_slug_3')
    I can see this text
@endroles

@roles(auth()->user()->hasRole('role_slug'))
    I can see this text
@endroles


@permission('permission_slug')
    I can see this text
@endpermission

@permission(auth()->user()->hasPermission('permission_slug'))
    I can see this text
@endpermission


@permissions('permission_slug_1', 'permission_slug_2', 'permission_slug_3')
    I can see this text
@endpermissions

@permissions(auth()->user()->hasPermission('permission_slug'))
    I can see this text
@endpermissions

You can only use blade directives with role/permission id or slug.

Note: use @can(), @role(), @roles(), @permission() and @permissions() directives is enabling separately. See config file.

Checking for permissions

A root role:

$user = User::find(1);

// Checks if the user has at least one role with root access:
$user->hasRootRole(): bool

user » role:

$user = User::find(1);

// with role slug:
$user->hasRole('role_slug'): bool

// with role ID:
$user->hasRole(1): bool

// with role instance:
$user->hasRole(Role::find(1)): bool

user » roles:

$user = User::find(1);

// with role slug:
$user->hasRoles('role_slug_1', 'role_slug_2'): bool

// with role slug as array:
$user->hasRoles(['role_slug_1', 'role_slug_2']): bool

// with role ID:
$user->hasRoles(1, 2, 3): bool

// with role instance:
$user->hasRoles(Role::find(1), Role::find(2)): bool

user » permission:

$user = User::find(1);

// with permission slug:
$user->hasPermission('permission_slug'): bool

// with permission ID:
$user->hasPermission(1): bool

// with permission instance:
$user->hasPermission(Permission::find(1)): bool

// If the `use_can_directive` option is set to true in the settings,
// then you can also check permissions through the `can` directive:
auth()->user()->can('permission_slug'): bool

user » permissions:

$user = User::find(1);

// with permission slug:
$user->hasPermissions('permission_slug_1', 'permission_slug_1'): bool

// with permission slug as array:
$user->hasPermissions(['permission_slug_1', 'permission_slug_1']): bool

// with permission ID:
$user->hasPermissions(1, 2, 3): bool

// with permission ID as array:
$user->hasPermissions([1, 2, 3]): bool

// with permission instance:
$user->hasPermissions(Permission::find(1), Permission::find(2)): bool

// with permission instance as array:
$user->hasPermissions([Permission::find(1), Permission::find(2)]): bool

role » permission:

$role = Role::find(1);

// with permission slug:
$role->hasPermission('permission_slug'): bool

// with permission ID:
$role->hasPermission(1): bool

// with permission instance:
$role->hasPermission(Permission::find(1)): bool

// If the `use_can_directive` option is set to true in the settings,
// then you can also check permissions through the `can` directive:
auth()->user()->can('permission_slug'): bool

role >> permissions:

$role = Role::find(1);

// with permission slug:
$role->hasPermissions('permission_slug_1', 'permission_slug_1'): bool

// with permission slug as array:
$role->hasPermissions(['permission_slug_1', 'permission_slug_1']): bool

// with permission ID:
$role->hasPermissions(1, 2, 3): bool

// with permission ID as array:
$role->hasPermissions([1, 2, 3]): bool

// with permission instance:
$role->hasPermissions(Permission::find(1), Permission::find(2)): bool

// with permission instance as array:
$role->hasPermissions([Permission::find(1), Permission::find(2)]): bool

Artisan commands

You can create/delete a role or a permission from a console with artisan commands:

php artisan acl:role-create {slug}
php artisan acl:role-delete {id|ID or role slug}

php artisan acl:permission-create {slug}
php artisan acl:permission-delete {id|ID or permission slug}

You can also invoke the creation of roles and permissions from your application:

Artisan::call('acl:role-create', ['slug' => $slug]);
Artisan::call('acl:role-delete', ['slug' => $slug]);

Artisan::call('acl:permission-create', ['slug' => $slug]);
Artisan::call('acl:permission-delete', ['slug' => $slug]);

License

This package is released under the MIT License.