nigam214/rbac

Powerful RBAC package for Laravel 5.3+

2.0.1 2017-11-08 04:42 UTC

Requires

• php: >=5.5.9
• illuminate/support: ~5.0

MIT

• Will G
• Ashish Nigam

• auth
• laravel
• roles
• permissions
• illuminate
• rbac

README

Powerful package for handling roles and permissions in Laravel 5.3

Based on the Bican/Roles Package.

Resources

• Packagist: https://packagist.org/packages/nigam214/rbac
• Github: https://github.com/nigam214/RBAC
• Forked From: https://github.com/DynamicCodeNinja/RBAC
• Based On: https://github.com/romanbican/roles

So whats New?

This package is forked from https://github.com/DynamicCodeNinja/RBAC and modified to open more control on RCAB. Package name has been changed to make it a new project. To make this package generic, user has been replaced by object. This RBAC can be applied to any object, not just the user.

So whats Different?

The difference is how Inheritance work. With Bican/Roles, permissions are inherited based on your highest role level.

Instead this package uses a parent_id column to enable roles to be inherited from each other.

This enables us to only pull permissions of roles that our users/objects inherits, or that are directly assigned to the user/object.

• Installation
  • Composer
  • Service Provider
  • Config File And Migrations
  • HasRoleAndPermission Trait And Contract
• Usage
  • Roles
    • Creating Roles
    • Attaching And Detaching Roles
    • Deny Roles
    • Checking For Roles
  • Permissions
    • Creating Permissions
    • Attaching And Detaching Permissions
    • Deny Permissions
    • Checking For Permissions
  • Inheritance
  • Entity Check
  • Blade Extensions
  • Middleware
• Config File
• More Information
• License

Installation

This package is very easy to set up. There are only couple of steps.

Composer

Pull this package in through Composer (file composer.json).

{
    "require": {
        "php": ">=5.5.9",
        "laravel/framework": "5.1.*",
        "nigam214/rbac": "~2.0"
    }
}

Run this command inside your terminal.

composer update

Service Provider

Add the package to your application service providers in config/app.php file.

'providers' => [

    /*
     * Laravel Framework Service Providers...
     */
    Illuminate\Foundation\Providers\ArtisanServiceProvider::class,
    Illuminate\Auth\AuthServiceProvider::class,
    ...

    /**
     * Third Party Service Providers...
     */
    Nigam214\RBAC\RBACServiceProvider::class,

],

Config File And Migrations

Publish the package config file and migrations to your application. Run these commands inside your terminal.

php artisan vendor:publish --provider="Nigam214\RBAC\RBACServiceProvider" --tag=config
php artisan vendor:publish --provider="Nigam214\RBAC\RBACServiceProvider" --tag=migrations

And also run migrations.

php artisan migrate

There must be created migration file for users table, which is in Laravel out of the box. For other custom object, there must be a migration file for the objects table.

HasRoleAndPermission Trait And Contract

Include HasRoleAndPermission trait and also implement HasRoleAndPermission contract inside your User model or Object model. Also, include $rbacName in your User model or Object model.

use Nigam214\RBAC\Traits\HasRoleAndPermission;
use Nigam214\RBAC\Contracts\HasRoleAndPermission as HasRoleAndPermissionContract;

class User extends Model implements AuthenticatableContract, CanResetPasswordContract, HasRoleAndPermissionContract
{
    use Authenticatable, CanResetPassword, HasRoleAndPermission;
    public $rbacName = "user_role_permission";

use Nigam214\RBAC\Traits\HasRoleAndPermission;
use Nigam214\RBAC\Contracts\HasRoleAndPermission as HasRoleAndPermissionContract;

class Object extends Model implements HasRoleAndPermissionContract
{
    use HasRoleAndPermission;
    public $rbacName = "user_role_permission";

If Role or Permission model is extends, then rbacName must be define in each models as given for User model.

rbacName must match with one of the name given in rbac config file.

And that's it!

Usage

Creating Roles

use Nigam214\RBAC\Models\Role;

$authUser = User::where('email' = $email)->first();

$adminRole = new Role([
    'name' => 'Admin',
    'slug' => 'admin',
    'description' => '', // optional
    'parent_id' => NULL, // optional, set to NULL by default
]);
$adminRole->owner_id = $authUser->id; // `owner_id` should match with config('rbac.owner.id')
$adminRole->save();

$moderatorRole = new Role([
    'name' => 'Forum Moderator',
    'slug' => 'forum.moderator',
]);
$moderatorRole->owner_id = $authUser->id; // `owner_id` should match with config('rbac.owner.id')
$moderatorRole->save();

Because of Slugable trait, if you make a mistake and for example leave a space in slug parameter, it'll be replaced with a dot automatically, because of str_slug function.

Attaching And Detaching Roles

It's really simple. You fetch a user/object from database and call attachRole method. There is BelongsToMany relationship between User/Object and Role model.

use App\User;

$authUser = User::where('email' = $email)->first();

$user = User::find($id);

$user->attachRole($adminRole, $authUser->id); //you can pass whole object, or just an id

$user->detachRole($adminRole); // in case you want to detach role
$user->detachAllRoles(); // in case you want to detach all roles

Example for Object model.

use App\Object;
$authUser = User::where('email' = $email)->first();
$object = Object::find($id);
$object->attachRole($adminRole, $authUser->id); //you can pass whole object, or just an id
$object->detachRole($adminRole); // in case you want to detach role
$object->detachAllRoles(); // in case you want to detach all roles

Deny Roles

To deny a user/objet a role and all of its children roles, see the following example.

We recommend that you plan your roles accordingly if you plan on using this feature. As you could easily lock out users/objects without realizing it.

use App\User;

$authUser = User::where('email' = $email)->first();

$role = Role::find($roleId);

$user = User::find($userId);
$user->attachRole($role, $authUser->id, FALSE); // Deny this role, and all of its decedents to the user regardless of what has been assigned.

use App\Object;

$authUser = User::where('email' = $email)->first();

$role = Role::find($roleId);

$object = Object::find($objectId);
$object->attachRole($role, $authUser->id, FALSE); // Deny this role, and all of its decedents to the object regardless of what has been assigned.

Checking For Roles

You can now check if the user/object has required role.

if ($user->roleIs('admin')) { // you can pass an id or slug
    //
}

You can also do this:

if ($user->roleIsAdmin()) {
    //
}

And of course, there is a way to check for multiple roles:

if ($user->roleIs('admin|moderator')) { // or $user->roleIs('admin, moderator') and also $user->roleIs(['admin', 'moderator'])
    // if user has at least one role
}

if ($user->roleIs('admin|moderator', true)) { // or $user->roleIs('admin, moderator', true) and also $user->roleIs(['admin', 'moderator'], true)
    // if user has all roles
}

As well as Wild Cards:

if ($user->roleIs('admin|moderator.*')) { // or $user->roleIs('admin, moderator.*') and also $user->roleIs(['admin', 'moderator.*'])
    //User has admin role, or a moderator role
}

Creating Permissions

It's very simple thanks to Permission model.

use Nigam214\RBAC\Models\Permission;

$authUser = User::where('email' = $email)->first();

$createUsersPermission = new Permission([
    'name' => 'Create users',
    'slug' => 'create.users',
    'description' => '', // optional
]);
$createUsersPermission->owner_id = $authUser->id; // `owner_id` should match with config('rbac.owner.id')
$createUsersPermission->save();

$deleteUsersPermission = new Permission([
    'name' => 'Delete users',
    'slug' => 'delete.users',
]);
$deleteUsersPermission->owner_id = $authUser->id; // `owner_id` should match with config('rbac.owner.id')
$deleteUsersPermission->save();

Attaching And Detaching Permissions

You can attach permissions to a role or directly to a specific user (and of course detach them as well).

use App\User;
use Nigam214\RBAC\Models\Role;

$authUser = User::where('email' = $email)->first();

$role = Role::find($roleId);
$role->attachPermission($createUsersPermission, $authUser->id); // permission attached to a role

$user = User::find($userId);
$user->attachPermission($deleteUsersPermission, $authUser->id); // permission attached to a user

$role->detachPermission($createUsersPermission); // in case you want to detach permission
$role->detachAllPermissions(); // in case you want to detach all permissions

$user->detachPermission($deleteUsersPermission);
$user->detachAllPermissions();

Deny Permissions

You can deny a user a permission, or you can deny an entire role a permission.

To do this, when attaching a permission simply pass a second parameter of false. This will deny that user that permission regardless of what they are assigned. Denied permissions take precedent over inherited and granted permissions.

use App\User;
use Nigam214\RBAC\Models\Role;

$authUser = User::where('email' = $email)->first();

$role = Role::find($roleId);
$role->attachPermission($createUsersPermission, $authUser->id, FALSE); // Deny this permission to all users who have or inherit this role.

$user = User::find($userId);
$user->attachPermission($deleteUsersPermission, $authUser->id, FALSE); // Deny this permission to this user regardless of what roles they are in.

Checking For Permissions

if ($user->can('create.users') { // you can pass an id or slug
    //
}

if ($user->canDeleteUsers()) {
    //
}

You can check for multiple permissions the same way as roles.

Inheritance

If you don't want the inheritance feature in you application, simply ignore the parent_id parameter when you're creating roles.

Roles that are assigned a parent_id of another role are automatically inherited when a user is assigned or inherits the parent role.

Here is an example:

You have 5 administrative groups. Admins, Store Admins, Store Inventory Managers, Blog Admins, and Blog Writers.

The Admins Role is the parent of both Store Admins Role as well as Blog Admins Role.

While the Store Admins Role is the parent to Store Inventory Managers Role.

And the Blog Admins Role is the parent to Blog Writers.

This enables the Admins Role to inherit both Store Inventory Managers Role and Blog Writers Role.

But the Store Admins Role only inherits the Store Inventory Managers Role,

And the Blog Admins Role only inherits the Blog Writers Role.

Another Example:

Here, admin inherits admin.user, admin.blog, and blog.writer.

While admin.user doesn't inherit anything, and admin.blog inherits blog.writer.

Nothing inherits development and, development doesn't inherit anything.

Entity Check

Let's say you have an article and you want to edit it. This article belongs to a user (there is a column user_id in articles table).

use App\Article;
use Nigam214\RBAC\Models\Permission;

$authUser = User::where('email' = $email)->first();

$editArticlesPermission = new Permission([
    'name' => 'Edit articles',
    'slug' => 'edit.articles',
    'model' => 'App\Article',
]);
$editArticlesPermission->owner_id = $authUser->id; // `owner_id` should match with config('rbac.owner.id')
$editArticlesPermission->save();

$user->attachPermission($editArticlesPermission, $authUser->id);

$article = Article::find(1);

if ($user->allowed('edit.articles', $article)) { // $user->allowedEditArticles($article)
    //
}

This condition checks if the current user is the owner of article. If not, it will be looking inside user permissions for a row we created before.

if ($user->allowed('edit.articles', $article, false)) { // now owner check is disabled
    //
}

Blade Extensions

There are three Blade extensions. Basically, it is replacement for classic if statements.

Blade extensions will only work for User model and get the valid user on blade page via Auth.

@role('admin') // @if(Auth::check() && Auth::user()->roleIs('admin'))
    // user is admin
@endrole

@permission('edit.articles') // @if(Auth::check() && Auth::user()->can('edit.articles'))
    // user can edit articles
@endpermission

@allowed('edit', $article) // @if(Auth::check() && Auth::user()->allowed('edit', $article))
    // show edit button
@endallowed

@role('admin|moderator', 'all') // @if(Auth::check() && Auth::user()->roleIs('admin|moderator', 'all'))
    // user is admin and also moderator
@else
    // something else
@endrole

Middleware

This package comes with VerifyRole and VerifyPermission middleware. You must add them inside your app/Http/Kernel.php file.

Blade extensions will only work for User model and get the valid user on blade page via Auth.

/**
 * The application's route middleware.
 *
 * @var array
 */
protected $routeMiddleware = [
    'auth' => \App\Http\Middleware\Authenticate::class,
    'auth.basic' => \Illuminate\Auth\Middleware\AuthenticateWithBasicAuth::class,
    'guest' => \App\Http\Middleware\RedirectIfAuthenticated::class,
    'role' => \Nigam214\RBAC\Middleware\VerifyRole::class,
    'permission' => \Nigam214\RBAC\Middleware\VerifyPermission::class,
];

Now you can easily protect your routes.

$router->get('/example', [
    'as' => 'example',
    'middleware' => 'role:admin',
    'uses' => 'ExampleController@index',
]);

$router->post('/example', [
    'as' => 'example',
    'middleware' => 'permission:edit.articles',
    'uses' => 'ExampleController@index',
]);

You also can pass multiple parameters on VerifyPermission and VerifyRole middleware, example: role:admin,moderator,true, the last parameter will be used to determine if user has all role or just any of the role passed, default value would be false.

It throws \Nigam214\RBAC\Exception\RoleDeniedException or \Nigam214\RBAC\Exception\PermissionDeniedException exceptions if it goes wrong.

You can catch these exceptions inside app/Exceptions/Handler.php file and do whatever you want.

/**
 * Render an exception into an HTTP response.
 *
 * @param  \Illuminate\Http\Request  $request
 * @param  \Exception  $e
 * @return \Illuminate\Http\Response
 */
public function render($request, Exception $e)
{
    if ($e instanceof \Nigam214\RBAC\Exceptions\RoleDeniedException) {
        // you can for example flash message, redirect...
        return redirect()->back();
    }

    return parent::render($request, $e);
}

Config File

You can change connection for models, slug separator, models path and there is also a handy pretend feature. Have a look at config file for more information.

More Information

This project is based on Bican/Roles.

License

This package is free software distributed under the terms of the MIT license.

I don't care what you do with it.

Contribute

I honestly don't know what I'm doing. If you see something that could be fixed. Make a pull request on the develop branch!.