nigam214/rbac

Powerful RBAC package for Laravel 5.3+

RBAC For Laravel 5.3

Powerful package for handling roles and permissions in Laravel 5.3, _(*1)

Based on the Bican/Roles Package., _(*2)

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., _(*3)

So whats Different?

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

Instead this package uses a parent_id column to enable roles to be inherited from each other., _(*5)

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

• 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., _(*7)

Composer

Pull this package in through Composer (file composer.json)., _(*8)

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

Run this command inside your terminal., _(*9)

composer update

Service Provider

Add the package to your application service providers in config/app.php file., _(*10)

'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., _(*11)

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

And also run migrations., _(*12)

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., _(*13)

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., _(*14)

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., _(*15)

rbacName must match with one of the name given in rbac config file., _(*16)

And that's it!, _(*17)

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., _(*18)

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., _(*19)

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., _(*20)

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., _(*21)

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., _(*22)

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., _(*23)

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

You can also do this:, _(*24)

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

And of course, there is a way to check for multiple roles:, _(*25)

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:, _(*26)

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., _(*27)

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)., _(*28)

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., _(*29)

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., _(*30)

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., _(*31)

Inheritance

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

Roles that are assigned a parent_id of another role are automatically inherited when a user is assigned or inherits the parent role., _(*33)

Here is an example:, _(*34)

You have 5 administrative groups. Admins, Store Admins, Store Inventory Managers, Blog Admins, and Blog Writers., _(*35)

The Admins Role is the parent of both Store Admins Role as well as Blog Admins Role., _(*36)

While the Store Admins Role is the parent to Store Inventory Managers Role., _(*37)

And the Blog Admins Role is the parent to Blog Writers., _(*38)

This enables the Admins Role to inherit both Store Inventory Managers Role and Blog Writers Role., _(*39)

But the Store Admins Role only inherits the Store Inventory Managers Role,, _(*40)

And the Blog Admins Role only inherits the Blog Writers Role., _(*41)

Another Example:, _(*42)

Here, admin inherits admin.user, admin.blog, and blog.writer., _(*43)

While admin.user doesn't inherit anything, and admin.blog inherits blog.writer., _(*44)

Nothing inherits development and, development doesn't inherit anything., _(*45)

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)., _(*46)

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., _(*47)

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., _(*48)

Blade extensions will only work for User model and get the valid user on blade page via Auth., _(*49)

@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., _(*50)

Blade extensions will only work for User model and get the valid user on blade page via Auth., _(*51)

/**
 * 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., _(*52)

$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., _(*53)

It throws \Nigam214\RBAC\Exception\RoleDeniedException or \Nigam214\RBAC\Exception\PermissionDeniedException exceptions if it goes wrong., _(*54)

You can catch these exceptions inside app/Exceptions/Handler.php file and do whatever you want., _(*55)

/**
 * 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., _(*56)

More Information

This project is based on Bican/Roles., _(*57)

License

This package is free software distributed under the terms of the MIT license., _(*58)

I don't care what you do with it., _(*59)

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!., _(*60)