Download the PHP package dlnsk/h-rbac without Composer
On this page you can find all versions of the php package dlnsk/h-rbac. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Package h-rbac
Short Description Based on native Laravel's gates and policies. Hierarchical RBAC with callbacks.
License MIT
Homepage https://github.com/dlnsk/h-rbac
Informations about the package h-rbac
h-rbac
Based on native Laravel's gates and policies. Hierarchical RBAC with callbacks.
In the process of creating my own projects I have formed an opinion about the minimum required ability of RBAC. It should allow:
- roles and permissions
- callbacks for permissions (for passing parameters in permission checking)
- permission's inheritance (to give different abilities to different roles)
- an optimal way to manage RBAC
Install
Supports Laravel since v5.1 to the latest (11.* and above).
Via Composer
Publish some cool stuff:
- config file (config/h-rbac.php) to configure role/permission
- example policy (app/Policies/PostPolicy.php) to configure chains and callbacks
with
php artisan vendor:publish --tag=hrbac-config
Add permissions, its chains and callbacks to policies.
Add roles and its permissions to config file. That's all!
Overview
This module is a wrapper for authorization logic and control access to resources of Laravel 5.1 and later.
Let's describe the minimum required ability of RBAC (in my opinion).
Roles and permissions
It's clear.
Callbacks for permissions
Very common situation is to allow user to change only his own posts. With this package it's simple:
and use as
You can pass any number of parameters in callback as array.
That's what you can do with Laravel's policies as it described in docs. But Laravel doesn't support roles.
Permission's inheritance
As you see callbacks are very useful. But what about a site manager who may edit any posts? Create separate permission? But which of them we should check?
Answer is to use chained (inherited) permissions. Example:
edit
-> editAnyPost
-> editPostInCategory
-> editOwnPost
Each of these permissions is placed into the appropriate role, but in code we always check the first (except in very rare cases):
These permissions in the chain will be checked one by one until one of it will pass. In other case the ability will be rejected for this user. So, we have many permissions with different business logic but checking in the code only one. This is the key!
The ways to manage RBAC
It is very popular to use database to store roles and permissions. It flexible but hard to support. Managing of roles and permissions required backend. When we start to use inheritance for permissions it becomes too difficult for direct changing.
Static roles
Most projects aren't large. It needs only a few roles and permissions, so backend becomes economically inexpedient. Thus, I believe that file driven RBAC is enough for many projects where users can have one or many roles simultaneously. Defining roles in config is visual and simple for support.
By default, roles applied to user store in database, so you should add an accessor to User
model to get list of roles.
Name of attribute you can change in config/h-rbac.php
if you need.
It doesn't matter how you store roles. Just return an array from function. You also can write and bind your
own RolesProvider
through DI
.
Static roles + overriding permissions
Some projects may suppose that administrator can override some user's permissions (include or exclude). If you have dozens of such users it's hard to make different roles for each. So overriding is a good choice.
It requires additional database table to store overrides. Publish migration with
php artisan vendor:publish --tag=hrbac-migrations
and bind EloquentPermissionProvider
inside your AppServiceProvider.php
bindings:
Now every record in permissions
table adds or removes one permission from user. You also can store additional value(s)
with an overridden permission. Here is the example:
Let's add the callback in PostPolicy
.
Now, if we add to permissions
table next record
we'll allow user with id = 100
edit any post in category with id = 5
.
The word exclude
may also be in action
field. This takes away the ability from user.
If both actions exists in database, the exclude
wins.
The field value
doesn't used by the module at all, so you can use any type for it or even a set of any extra fields.
Different way
Keep in mind that you can bind your own RolesProvider
or/and PermissionsProvider
and store roles and permissions
as you wish. It's very flexible.
Usage
As we said h-rbac
is a wrapper for authorization logic
since Laravel 5.1 to this time. So, you can use any features of it.
From User model:
In controller:
Within Blade
@can('edit', $post)
<!-- The Current User Can Update The Post -->
@else
<!-- The Current User Can't Update The Post -->
@endcan
Also in h-rbac
we have added directive @role
which you can combine with @else
@role('user|manager')
<!-- Current user has any of those roles -->
@endrole
Permission without model
Native Laravel's permissions hard linked with models. So the model object or model class are required to check ability, because it defines a right Policy that includes callbacks:
If your permission isn't linked to model you can use policy class as a place to search the chain and callbacks:
and with additional parameters:
The policy class should be the first element in array or it may has a key:
Configuration
Permissions
Permissions and callbacks are defining in Policies as it describes in docs. Innovation is the chains of permissions.
You should add callback only if you need additional check for this permission. The name of callback should be camelcased name of permission.
The logic of checking permissions
We check all permissions in chain one by one and:
- allow if user has a permission with no callback
- allow if user has a permission and callback return true
- deny if user don't have all permission in chain
- deny if callbacks of all user's permissions return false
If the check allows the user to do something, all remaining permission in chain will be pass.
Keep in mind that you can define your own PermissionChecker
to change this logic.
Roles
Roles are defining in config file (config/h-rbac.php)
If you want to store assigning permissions to roles in database, just make your
own RolesProvider
to change this logic.
Change log
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONDUCT for details.
Credits
- Dmitry Pupinin
- All Contributors
License
The MIT License (MIT). Please see License File for more information.