usage

Usage

With routes and methods

Permissions Handler comes with three middlewares MethodMiddleware, PermissionMiddleware and RoleMiddleware

MethodMiddleware

This middleware will check for annotations written for your methods and check the permisions and roles assigned to this method, register this middleware into your kernel.php under $middleware to use it globaly over your system or middlewareGroups to use over groups or register it anywhere else according to you needs.

/**
* @Permissions({"add-posts"})
*/
function store(Request $request){
    // your code here
}

/**
* @Roles({"admin"})
*/
function delete(Request $request){
    // your code here
}

 
/**
* @Owns(relation="posts", parameter="id")
*/
function update(Request $request){
    // your code here
}

Permissions and Roles accepts array of permissions and roles in format {"add-users", "view-users"} and {"super-admin", "admin"} respectively.

You can pass extra optional parameter requireAll=true (default is false) to enforce the user to has all the permissions and roles to be able to access the method, for example

/**
* @Permissions({"add-posts", "edit-posts"}, requireAll=true)
*/
function store(Request $request){
    // your code here
}

Owns annotation dives more deeper, its used to ensure that the user owns a specific resource, for example, only the post owner can edit the post, so you need to ensure that the user own the post via a relation.
Paramters:

• relation (required)
  the eloquent relation
• parameter (required)
  the request paramter which PermissionsHandler get its value from the request, for example parameter="id" then PermissionsHandler will search for parameter "id" in the request $request->id.
• key (optional)
  $user->{$this->relation}->contains($this->key, $request->{$this->attribute});
  as you see key is the attribute that we search by. by default the parameter paramter is the key paramters unless you decide something else then you have to deine your parameter and key parameter.

PermissionMiddleware

This middleware used to handle the permissions for specific groups or routes.
register the route into the kernel.php

protected $routeMiddleware = [
    'permissions' => PermissionsHandler\Middleware\PermissionMiddleware::class
]

then you can use it as the following:

// permissions
Route::group(['middleware' => ['permissions:add-user']], function () {
    //
});

If you need to pass more than one permission, you can pass them with the following format add-user|edit-user.
The middleware accepts additional boolean parameter $requireAll, it validates that the user must has all the permissions in the first parameter, default is false.

RoleMiddleware

This middleware used to handle the roles for specific groups or routes.
It's working the same as PermissionsMiddleware

Blade Directives

PermissionsHandler comes with some useful blade directives

• @can Due to the integration with the built-in laravel Gate, so you can simply use the can directive as the following can ensures that the logged in user has a specific permission
  
  examples: @can('edit-users)

• @permission @permissions directive ensures that that authenticated user as a permission or a set of permissions
  
  examples: @permission('delete-users') // accepts string
  @permission(['edit-users', 'delete-users']) // accepts array of strings
  @permission($permissionModel) // accepts model
  @permission($collectionoOfPermissions) // accepts Collection
  
  @permission directive accepts second paramter requireAll=false|true when this parameter is false that means the user should has at least one permission not nessissary all, with true then he should has all the permissions passed in the first arguments.

• @role @role directive ensures that that authenticated user as a role or a set of roles
  
  examples: @role('user') // accepts string
  @role(['admin', 'super-admin']) // accepts array of strings
  @role($roleModel) // accepts model
  @role($collectionoOfRoles) // accepts Collection
  
  @role directive accepts second parameter requireAll=false|true when this parameter is false that means the user should has at least one role not necessary all, with true then he should has all the permissions passed in the first arguments.

Within your code

User

• check for permissions

$hasPermission = $user->hasPermission('add-users'); 
// or
$hasPermission = $user->hasPermission(['add-users', 'view-users']); // default requireAll is false
// or has all of these permissions
$hasPermission = $user->hasPermission(['add-users', 'view-users'], true);
// or
$hasPermission = $user->hasPermission($permissionModel);
// or
$hasPermission = $user->hasPermission($collectionOfPermissionModel); // default requireAll is false
// or
$hasPermission = $user->hasPermission($collectionOfPermissionModel, true);

• check for roles

$hasRole = $user->hasRole('user'); 
// or
$hasRole = $user->hasRole(['amdin', 'super-admin']); // default requireAll is false
// or has all of these roles
$hasRole = $user->hasRole(['admin', 'super-admin'], true);
// or
$hasRole = $user->hasRole($roleModel);
// or
$hasRole = $user->hasRole($collectionOfRoleModel); // default requireAll is false
// or user must has all of these roles
$hasRole = $user->hasRole($collectionOfRoleModel, true);

• assign roles

$user->assignRole('admin'); // as a string
$user->assignRole('admin', 'super-admin'); // as parameters
$user->assignRole(['admin', 'super-admin']); // as array of strings
$user->assignRole($userModel); // as a Model
$user->assignRole($adminModel, $superAdminModel); // as parameters
$user->assignRole($rolesCollection); // as a Collection

• revoke roles

$user->revokeRole('admin'); // as a string
$user->revokeRole('admin', 'super-admin'); // as parameters
$user->revokeRole(['admin', 'super-admin']); // as array of strings
$user->revokeRole($userModel); // as a Model
$user->revokeRole($adminModel, $superAdminModel); // as parameters
$user->revokeRole($rolesCollection); // as a Collection

Role

• check for permissions

$hasPermission = $role->hasPermission('add-users'); 
// or
$hasPermission = $role->hasPermission(['add-users', 'view-users']); // default requireAll is false
// or has all of these permissions
$hasPermission = $role->hasPermission(['add-users', 'view-users'], true);
// or
$hasPermission = $role->hasPermission($permissionModel);
// or
$hasPermission = $role->hasPermission($collectionOfPermissionModel); // default requireAll is false
// or
$hasPermission = $role->hasPermission($collectionOfPermissionModel, true);

• assign permissions

$role->assignPermission('add-users'); // as a string
$role->assignPermission('add-users', 'edit-users'); // as parameters
$role->assignPermission(['add-users', 'edit-users']); // as array of strings
$role->assignPermission($permissionModel); // as a Model
$role->assignPermission($permissionModel1, $permissionModel2); // as parameters
$role->assignPermission($permissionsCollection); // as a Collection

• revoke permissions

$role->revokePermission('add-users'); // as a string
$role->revokePermission('add-users', 'edit-users'); // as parameters
$role->revokePermission(['add-users', 'edit-users']); // as array of strings
$role->revokePermission($permissionModel); // as a Model
$role->revokePermission($permissionModel1, $permissionModel2); // as parameters
$role->revokePermission($permissionsCollection); // as a Collection

Artisan commands

• Add permission
  php artisan permissions:add --permission=add-users

• Add Role
  php artisan permissions:add --role=admin

• Assign permission to role
  php artisan permissions:assign --role=admin --permission=add-users

• Assign role to user
  php artisan permissions:assign --role=admin --user-id=5

• Clear cached annoations
  php artisan permissions:clear-cache --annotations

• Clear cached database
  php artisan permissions:clear-cache --db