Shinobi
Shinobi brings a simple and light-weight role-based permissions system to Laravel's built in Auth system.
ACL (Access Control List)
- Every user can have zero or more permissions.
- Every user can have zero or more roles.
- Every role can have zero or more permissions.
- Every role can have one of two special flags,
all-access
andno-access
Installation
Simply install the package through Composer. From here the package will automatically register its service provider and Shinobi
facade.
composer require caffeinated/shinobi
We will document both versions 3.4
and 4.0
. Both versions support Laravel 5.8
. If you are currently on the 3.x
release, please take this time to upgrade to the latest version ✌️
Middleware
Shinobi provides middleware that you may assign to specific routes in your application. To register, simply append the following middleware to your app/Http/Kernel.php
file under the $routeMiddleware
property.
Check If User Has A Given Role
'has.role' => \Caffeinated\Shinobi\Middleware\UserHasRole::class,
Check If User Has A Given Permission
This is available in Shinobi 3.4
. 4.0
does not include this as it hooks in to Laravel's gate system. If using Laravel 5.8
and Shinobi 4.0
, simply use Laravel's can
middleware to check permissions.
'has.permission' => \Caffeinated\Shinobi\Middleware\UserHasPermission::class,
Migrations
Publish the provided migration files with the vendor:publish
Artisan command.
php artisan vendor:publish --provider="Caffeinated\Shinobi\ShinobiServiceProvider"
Usage
4.0
Add the HasRolesAndPermissions
trait to your User
model.
use Illuminate\Foundation\Auth\User as Authenticatable;
use Caffeinated\Shinobi\Concerns\HasRolesAndPermissions;
class User extends Authenticatable
{
use HasRolesAndPermissions;
...
}
roles
Returns assigned roles for the given user.
$roles = auth()->user()->roles;
hasRole
Checks if the given user has the specified role.
$isEditor = auth()->user()->hasRole('editor');
assignRoles
Assign the given role(s) to the user, by their slug.
auth()->user()->assignRoles('editor', 'vip');
removeRoles
Remove the given role(s) from the user, by their slug.
auth()->user()->removeRoles('vip');
syncRoles
Sync the given role(s) for the user, by their slug. Any roles not provided will be removed from the user.
auth()->user()->syncRoles('moderator');
permissions
Returns assigned permissions for the given user (or role).
$permissions = auth()->user()->permissions;
hasPermissionTo
Checks if the given user (or role) has the specified permission.
$isEditor = auth()->user()->hasPermissionTo('edit.pages');
can
The can
method provided by Laravel may also be used. Behind the scenes, the gate policies Shinobi registers runs permissions through the hasPermissionTo
method detailed above ✌️
givePermissionTo
Give the user (or role) specific permission(s).
auth()->user()->givePermissionTo('edit.pages', 'create.pages', 'delete.pages');
revokePermissionTo
Revoke the given permission(s) from the user (or role).
auth()->user()->revokePermissionTo('access.admin');
syncPermissions
Sync the given permission(s) against the user (or role). Any permissions not specified will be revoked.
auth()->user()->syncPermissions('edit.users', 'create.users', 'delete.users', 'view.users');
3.4
Add the ShinobiTrait
trait to your User
model.
use Caffeinated\Shinobi\Traits\ShinobiTrait;
use Illuminate\Foundation\Auth\User as Authenticatable;
class User extends Authenticatable
{
use ShinobiTrait;
...
}
Roles vs. Permissions
It's better for your application in the long run to simply check against permissions rather than specific roles. Roles are interchangeable and dynamic, having the ability to be assigned fine-grained permissions.
So instead of checking if a user has an admin
role, check for a access.admin
permission. In the future you may want to add Editors or Moderators that will need access to your admin section. If you hard coded the role in your code, you'd have to backtrack every instance where it checks for an admin
role and add in conditionals for editor
and moderator
. Much easier to simply assign the access.admin
permission to your Editor and Moderator roles and be done ✌️