- Notifications
You must be signed in to change notification settings - Fork294
Powerful package for handling roles and permissions in Laravel 5
License
romanbican/roles
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
Powerful package for handling roles and permissions in Laravel 5 (5.1 and also 5.0).
This package is very easy to set up. There are only couple of steps.
Pull this package in through Composer (filecomposer.json).
{"require":{"php":">=5.5.9","laravel/framework":"5.1.*","bican/roles":"2.1.*"}}
If you are still using Laravel 5.0, you must pull in version
1.7.*.
Run this command inside your terminal.
composer updateAdd the package to your application service providers inconfig/app.php file.
'providers' => [/* * Laravel Framework Service Providers... */Illuminate\Foundation\Providers\ArtisanServiceProvider::class,Illuminate\Auth\AuthServiceProvider::class, .../** * Third Party Service Providers... */Bican\Roles\RolesServiceProvider::class,],
Publish the package config file and migrations to your application. Run these commands inside your terminal.
php artisan vendor:publish --provider="Bican\Roles\RolesServiceProvider" --tag=configphp artisan vendor:publish --provider="Bican\Roles\RolesServiceProvider" --tag=migrationsAnd also run migrations.
php artisan migrateThis uses the default users table which is in Laravel. You should already have the migration file for the users table available and migrated.
IncludeHasRoleAndPermission trait and also implementHasRoleAndPermission contract inside yourUser model.
useBican\Roles\Traits\HasRoleAndPermission;useBican\Roles\Contracts\HasRoleAndPermissionasHasRoleAndPermissionContract;class Userextends Modelimplements AuthenticatableContract, CanResetPasswordContract, HasRoleAndPermissionContract{use Authenticatable, CanResetPassword, HasRoleAndPermission;
And that's it!
useBican\Roles\Models\Role;$adminRole = Role::create(['name' =>'Admin','slug' =>'admin','description' =>'',// optional'level' =>1,// optional, set to 1 by default]);$moderatorRole = Role::create(['name' =>'Forum Moderator','slug' =>'forum.moderator',]);
Because of
Slugabletrait, if you make a mistake and for example leave a space in slug parameter, it'll be replaced with a dot automatically, because ofstr_slugfunction.
It's really simple. You fetch a user from database and callattachRole method. There isBelongsToMany relationship betweenUser andRole model.
useApp\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
You can now check if the user has required role.
if ($user->is('admin')) {// you can pass an id or slug// or alternatively $user->hasRole('admin')}
You can also do this:
if ($user->isAdmin()) {//}
And of course, there is a way to check for multiple roles:
if ($user->is('admin|moderator')) {/* | Or alternatively: | $user->is('admin, moderator'), $user->is(['admin', 'moderator']), | $user->isOne('admin|moderator'), $user->isOne('admin, moderator'), $user->isOne(['admin', 'moderator']) */// if user has at least one role}if ($user->is('admin|moderator',true)) {/* | Or alternatively: | $user->is('admin, moderator', true), $user->is(['admin', 'moderator'], true), | $user->isAll('admin|moderator'), $user->isAll('admin, moderator'), $user->isAll(['admin', 'moderator']) */// if user has all roles}
When you are creating roles, there is optional parameterlevel. It is set to1 by default, but you can overwrite it and then you can do something like this:
if ($user->level() >4) {//}
If user has multiple roles, method
levelreturns the highest one.
Level has also big effect on inheriting permissions. About it later.
It's very simple thanks toPermission model.
useBican\Roles\Models\Permission;$createUsersPermission = Permission::create(['name' =>'Create users','slug' =>'create.users','description' =>'',// optional]);$deleteUsersPermission = Permission::create(['name' =>'Delete users','slug' =>'delete.users',]);
You can attach permissions to a role or directly to a specific user (and of course detach them as well).
useApp\User;useBican\Roles\Models\Role;$role = Role::find($roleId);$role->attachPermission($createUsersPermission);// permission attached to a role$user = User::find($userId);$user->attachPermission($deleteUsersPermission);// 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();
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. You can make use of additional methods likecanOne,canAll orhasPermission.
Role with higher level is inheriting permission from roles with lower level.
There is an example of thismagic:
You have three roles:user,moderator andadmin. User has a permission to read articles, moderator can manage comments and admin can create articles. User has a level 1, moderator level 2 and admin level 3. It means, moderator and administrator has also permission to read articles, but administrator can manage comments as well.
If you don't want permissions inheriting feature in you application, simply ignore
levelparameter when you're creating roles.
Let's say you have an article and you want to edit it. This article belongs to a user (there is a columnuser_id in articles table).
useApp\Article;useBican\Roles\Models\Permission;$editArticlesPermission = Permission::create(['name' =>'Edit articles','slug' =>'edit.articles','model' =>'App\Article',]);$user->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.
if ($user->allowed('edit.articles',$article,false)) {// now owner check is disabled//}
There are four Blade extensions. Basically, it is replacement for classic if statements.
@role('admin')// @if(Auth::check() && Auth::user()->is('admin'))// user is admin@endrole@permission('edit.articles')// @if(Auth::check() && Auth::user()->can('edit.articles'))// user can edit articles@endpermission@level(2)// @if(Auth::check() && Auth::user()->level() >= 2)// user has level 2 or higher@endlevel@allowed('edit',$article)// @if(Auth::check() && Auth::user()->allowed('edit', $article))// show edit button@endallowed@role('admin|moderator','all')// @if(Auth::check() && Auth::user()->is('admin|moderator', 'all'))// user is admin and also moderator@else// something else@endrole
This package comes withVerifyRole,VerifyPermission andVerifyLevel middleware. You must add them inside yourapp/Http/Kernel.php file.
/** * 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' => \Bican\Roles\Middleware\VerifyRole::class,'permission' => \Bican\Roles\Middleware\VerifyPermission::class,'level' => \Bican\Roles\Middleware\VerifyLevel::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',]);$router->get('/example', ['as' =>'example','middleware' =>'level:2',// level >= 2'uses' =>'ExampleController@index',]);
It throws\Bican\Roles\Exceptions\RoleDeniedException,\Bican\Roles\Exceptions\PermissionDeniedException or\Bican\Roles\Exceptions\LevelDeniedException exceptions if it goes wrong.
You can catch these exceptions insideapp/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 */publicfunctionrender($request,Exception$e){if ($einstanceof \Bican\Roles\Exceptions\RoleDeniedException) {// you can for example flash message, redirect...returnredirect()->back(); }returnparent::render($request,$e);}
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.
For more information, please have a look atHasRoleAndPermission contract.
This package is free software distributed under the terms of the MIT license.
About
Powerful package for handling roles and permissions in Laravel 5