Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/zanysoft/laravel-roles

A Powerful package for handling roles and permissions in Laravel
https://github.com/zanysoft/laravel-roles

Last synced: 10 months ago
JSON representation

A Powerful package for handling roles and permissions in Laravel

Awesome Lists containing this project

README 

          
# Roles And Permissions For Laravel.

[![Laravel](https://img.shields.io/badge/Laravel-5.x-orange.svg?style=flat-square)](http://laravel.com)

[![License](http://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square)](https://tldrlegal.com/license/mit-license)

[![Downloads](https://img.shields.io/packagist/dt/zanysoft/laravel-roles.svg?style=flat-square)](https://packagist.org/packages/zanysoft/laravel-roles)



A Powerful package for handling roles and permissions in Laravel.



- [Installation](#installation)

    - [Composer](#composer)

    - [Service Provider](#service-provider)

    - [Config File And Migrations](#config-file-and-migrations)

    - [HasRoleAndPermission Trait And Contract](#hasroleandpermission-trait-and-contract)

    - [Migrations and Seeds](#migrations-and-seeds)

    - [Migrate from Bican roles](#Migrate-from-bican-roles)

- [Usage](#usage)

    - [Creating Roles](#creating-roles)

    - [Attaching, Detaching and Syncing Roles](#attaching-detaching-and-syncing-roles)

    - [Assign a user role to new registered users](#assign-a-user-role-to-new-registered-users)

    - [Checking For Roles](#checking-for-roles)

    - [Creating Permissions](#creating-permissions)

    - [Attaching, Detaching and Syncing Permissions](#attaching-detaching-and-syncing-permissions)

    - [Checking For Permissions](#checking-for-permissions)

    - [Permissions Inheriting](#permissions-inheriting)

    - [Entity Check](#entity-check)

    - [Blade Extensions](#blade-extensions)

    - [Middleware](#middleware)

- [Config File](#config-file)

- [More Information](#more-information)

- [Opening an Issue](#opening-an-issue)

- [License](#license)



---



## Installation



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



### Composer



Pull this package in through Composer

```

composer require zanysoft/laravel-roles

```



### Service Provider

* Laravel 5.5 and up

Uses package auto discovery feature, no need to edit the `config/app.php` file.



* Laravel 5.4 and below

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



```php

'providers' => [



    ...



    /**

     * Third Party Service Providers...

     */

    ZanySoft\LaravelRoles\RolesServiceProvider::class,



],

```



### Config File



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



    php artisan vendor:publish --tag=laravelroles



### HasRoleAndPermission Trait And Contract



1. Include `HasRoleAndPermission` trait and also implement `HasRoleAndPermission` contract inside your `User` model. See example below.



2. Include `use ZanySoft\LaravelRoles\Traits\HasRoleAndPermission;` in the top of your `User` model below the namespace and implement the `HasRoleAndPermission` trait. See example below.



Example `User` model Trait And Contract:



```php



 This uses the default users table which is in Laravel. You should already have the migration file for the users table available and migrated.



1. Setup the needed tables:



    `php artisan migrate`



2. Update `database\seeds\DatabaseSeeder.php` to include the seeds. See example below.



```php

call('PermissionsTableSeeder');

            $this->call('RolesTableSeeder');

            $this->call('ConnectRelationshipsSeeder');

            //$this->call('UsersTableSeeder');



        Model::reguard();

    }

}



```



3. Seed an initial set of Permissions, Roles, and Users with roles.



```

composer dump-autoload

php artisan db:seed

```



#### Roles Seeded

|Property|Value|

|----|----|

|Name| Admin|

|Slug| admin|

|Description| Admin Role|

|Level| 5|



|Property|Value|

|----|----|

|Name| User|

|Slug| user|

|Description| User Role|

|Level| 1|



|Property|Value|

|----|----|

|Name| Unverified|

|Slug| unverified|

|Description| Unverified Role|

|Level| 0|



#### Permissions Seeded:

|Property|Value|

|----|----|

|name|Can View Users|

|slug|view.users|

|description|Can view users|

|model|Permission|



|Property|Value|

|----|----|

|name|Can Create Users|

|slug|create.users|

|description|Can create new users|

|model|Permission|



|Property|Value|

|----|----|

|name|Can Edit Users|

|slug|edit.users|

|description|Can edit users|

|model|Permission|



|Property|Value|

|----|----|

|name|Can Delete Users|

|slug|delete.users|

|description|Can delete users|

|model|Permission|



### And that's it!



---

## Usage



### Creating Roles



```php

use ZanySoft\LaravelRoles\Models\Role;



$adminRole = Role::create([

    'name' => 'Admin',

    'slug' => 'admin',

    'description' => '',

    'level' => 5,

]);



$moderatorRole = Role::create([

    'name' => 'Forum Moderator',

    'slug' => 'forum.moderator',

]);

```



> 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, Detaching and Syncing Roles



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



```php

use App\User;



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



$user->attachRole($adminRole); // 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

$user->syncRoles($roles); // you can pass Eloquent collection, or just an array of ids

```



### Assign a user role to new registered users



You can assign the user a role upon the users registration by updating the file `app\Http\Controllers\Auth\RegisterController.php`.

You can assign a role to a user upon registration by including the needed models and modifying the `create()` method to attach a user role. See example below:



* Update the top of `app\Http\Controllers\Auth\RegisterController.php`:



```php

 $data['name'],

            'email' => $data['email'],

            'password' => bcrypt($data['password']),

        ]);



        $role = Role::where('name', '=', 'User')->first();  //choose the default role upon user creation.

        $user->attachRole($role);



        return $user;



    }

```



### Checking For Roles



You can now check if the user has required role.



```php

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

    //

}

```



You can also do this:



```php

if ($user->isAdmin()) {

    //

}

```



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



```php

if ($user->hasRole(['admin', 'moderator'])) {

    /*

    | Or alternatively:

    | $user->hasRole('admin, moderator'), $user->hasRole('admin|moderator'),

    | $user->hasOneRole('admin, moderator'), $user->hasOneRole(['admin', 'moderator']), $user->hasOneRole('admin|moderator')

    */



    // The user has at least one of the roles

}



if ($user->hasRole(['admin', 'moderator'], true)) {

    /*

    | Or alternatively:

    | $user->hasRole('admin, moderator', true), $user->hasRole('admin|moderator', true),

    | $user->hasAllRoles('admin, moderator'), $user->hasAllRoles(['admin', 'moderator']), $user->hasAllRoles('admin|moderator')

    */



    // The user has all roles

}

```



### Creating Permissions



It's very simple thanks to `Permission` model.



```php

use ZanySoft\LaravelRoles\Models\Permission;



$createUsersPermission = Permission::create([

    'name' => 'Create users',

    'slug' => 'create.users',

    'description' => '', // optional

]);



$deleteUsersPermission = Permission::create([

    'name' => 'Delete users',

    'slug' => 'delete.users',

]);

```



### Attaching, Detaching and Syncing Permissions



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



```php

use App\User;

use ZanySoft\LaravelRoles\Models\Role;



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

$role->attachPermission($createUsersPermission); // permission attached to a role



```



```php

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

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

$role->syncPermissions($permissions); // you can pass Eloquent collection, or just an array of ids



```



### Checking For Permissions



```php

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

    //

}



if ($user->canDeleteUsers()) {

    //

}

```



You can check for multiple permissions the same way as roles. You can make use of additional methods like `hasOnePermission` or `hasAllPermissions`.



### Permissions Inheriting



Role with higher level is inheriting permission from roles with lower level.



There is an example of this `magic`:



You have three roles: `user`, `moderator` and `admin`. User has a permission to read articles, moderator can manage comments and admin can create articles.



> If you don't want permissions inheriting feature in you application, simply ignore `level` parameter when you're creating roles.



### 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).



```php

use App\Article;

use ZanySoft\LaravelRoles\Models\Permission;



$editArticlesPermission = Permission::create([

    'name' => 'Edit articles',

    'slug' => 'edit.articles',

    'model' => 'App\Article',

]);



$role->attachPermission($editArticlesPermission);



$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.



```php

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

    //

}

```



### Blade Extensions



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



```php

@role('admin') // @if(Auth::check() && Auth::user()->hasRole('admin'))

    // user has admin role

@endrole



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

    // user has edit articles permissison

@endpermission



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

    // show edit button

@endallowed



@role('admin|moderator', true) // @if(Auth::check() && Auth::user()->hasRole('admin|moderator', true))

    // user has admin and moderator role

@else

    // something else

@endrole

```



### Helper Functions



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



```php

@if(hasRole('admin')) // @if(Auth::check() && Auth::user()->hasRole('admin'))

    // user has admin role

@endif



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

    // user has edit articles permissison

@endif



@if(can('create.articles|edit.articles',true)) // @if(Auth::check() && Auth::user()->hasPermission('create.articles|edit.articles'))

    // user has create and edit articles permissison

@endif



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

    // user has edit articles permissison

@endif



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

    // show edit button

@endif



@if(hasRole('admin|moderator', true)) // @if(Auth::check() && Auth::user()->hasRole('admin|moderator', true))

    // user has admin and moderator role

@else

    // something else

@endif

```



### Middleware



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



```php

/**

 * 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' => \ZanySoft\LaravelRoles\Middleware\VerifyRole::class,

    'permission' => \ZanySoft\LaravelRoles\Middleware\VerifyPermission::class,

    'level' => \ZanySoft\LaravelRoles\Middleware\VerifyLevel::class,

];

```



Now you can easily protect your routes.



```php

Route::get('/', function () {

    //

})->middleware('role:admin');



Route::get('/', function () {

    //

})->middleware('permission:edit.articles');



Route::group(['middleware' => ['role:admin']], function () {

    //

});



```



---



## 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

For more information, please have a look at [HasRoleAndPermission](https://github.com/zanysoft/laravel-roles/blob/master/src/Contracts/HasRoleAndPermission.php) contract.



## Opening an Issue

Before opening an issue there are a couple of considerations:

* A **star** on this project shows support and is way to say thank you to all the contributors. If you open an issue without a star, *your issue may be closed without consideration.* Thank you for understanding and the support. You are all awesome!

* **Read the instructions** and make sure all steps were *followed correctly*.

* **Check** that the issue is not *specific to your development environment* setup.

* **Provide** *duplication steps*.

* **Attempt to look into the issue**, and if you *have a solution, make a pull request*.

* **Show that you have made an attempt** to *look into the issue*.

* **Check** to see if the issue you are *reporting is a duplicate* of a previous reported issue.

* **Following these instructions show me that you have tried.**

* If you have a questions send me an email to info@zanysoft.com



## License

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