Download the PHP package liutauras/laravel-roles-permissions without Composer
On this page you can find all versions of the php package liutauras/laravel-roles-permissions. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download liutauras/laravel-roles-permissions
More information about liutauras/laravel-roles-permissions
Files in liutauras/laravel-roles-permissions
Package laravel-roles-permissions
Short Description Simple but powerful package for handling roles and permissions in Laravel
License MIT
Homepage https://github.com/centeron/laravel-roles-permissions
Informations about the package laravel-roles-permissions
Roles and Permissions for Laravel (RBAC)
- Description
- Installation
- Usage
- Creating, deleting, inheriting roles and permissions
- Attaching roles and permissions to users
- Using via trait
- Using via gate
- Using via middleware
- Using via Blade directives
- Artisan commands
- Advanced usage of permissions
- Cache
- Database structure
Description
Laravel has Access Control List (ACL) out of the box to work with user permissions. However, if you need to build a flexible access system based on roles and permissions with an inheritance, take into account their trigger logic. Futhermore, saving all of that in a database the basic functionallity will not be enough. The current laravel package is a simple powerful instument which allows development of both regular RBAC and the most complicated systems via simple integration within your application.
What does this package support?
- Multiple user models
- Infinite inheritance for roles and permissions (with checking of infinite looping)
- Multiple roles and permissions for users
- Expandability of auth items (roles, permissions, ...) in cases of separation them by guard or something else
- Setting the logic of permission triggering (see Advanced usage)
- Checking roles and permissions by their given names, id or class instances
- Rights checking via trait, gate, middleware, blade directives
- Ability to enable and disable the cache
- Artisan-commands for working with RBAC
Installation
You can install the package via composer:
You can publish the config file with:
After the command has been executed you can change database table names in config/permissions.php
file.
You also can change cache settings.
Publish the migration with:
And perform the migration:
Usage
First of all add the trait Centeron\Permissions\Traits\HasAuthItems
to your model User
Now User
can add roles and permissions, check ability for access, etc. Every user can attach multiple roles and permissions.
Permissions can be attached to roles, models and other parent permissions. The same opportunities are available for roles.
In fact there is no real difference between role and permission. It is merely a formal devision of authoriztion items (auth-items) for logic types.
Feel free to add as much new types of auth-items as you need in your laravel application.
Creating, deleting, inheriting roles and permissions
To add new role or permission:
AuthItem
is an extended Eloquent model. So you can use any Eloquent-command you need including deleting:
Using addChilds
and addParents
you can add parent and child items, organizing hierarchy of any depth you require:
Similarly removeChilds
and removeParents
remove these relations (without deleting entitities AuthItem
themselves).
In the example above the variables are instances of AuthItem
. However you can use names of roles and permissions or even their ID
as parameters. Method recognizes how to work with these parameteres by parameter`s types (int/string/class). I.e.
the next code will work correctly as well:
You can check whether the item has rights of other items (in other words whether is a child in any generation) with the fucntion
hasAny
(has any of the given items) and hasAll
(has all of the given items). Of course, these methods are equal if has been
given only one parameter.
Attaching roles and permissions to users
Empowering models can occur as from model side using a trait. Centeron\Permissions\Traits\HasAuthItems
:
as from roles/permission`s side giving assigning models as parameters to them:
A permission (role) can be detached from a user using detachAuthItems
:
Using via trait
You can determine if a user has roles and permissions:
But there can be a case when users should only edit own posts, or only if they have approptiate rating for that. In such cases we have to use other functions:
More about conditional access in chapter Advanced usage
Using via gate
The standard way to check rights using facade Gate
also works. You still may use methods
check
, allow
and denies
of Gate
:
You do not need to use method define
. All definitions are housed in the database. Rights inheritance is taken into account.
In controllers you may use helper as well:
Using via middleware
You can protect your routes using middleware rules with a middleware can
which is available out of the box:
Using via Blade directives
In view
files it is convenient to use Blade directives:
For conditional permissions the following directives should be:
More about conditional access in chapter Advanced usage
Artisan commands
The current package provides a full list of necessary console commands to work with RBAC:
Advanced usage of permissions
An overwhelming majority of RBAC usage doesn't need any logic for their triggering. We mark areas by string identifiers and then check whether the user has permision for that particular area. Sometimes this is not enough. What if a user only needs to edit their own posts or posts which belong to certain categories? What is more categories could be added in process of time. In such situations, recoding isn’t always necessary.
We should be able, firstly, to provide the triggering logic to permissions and secondly, to retain relevant data which might be required for these rules.
For this purpose Centeron\Permissions\Models\AuthItem
has 2 properties (columns in a table):
rule
- stores the name of the class responsible for triggering logicdata
- stores data in a serialized form that may be required working with the current object.
rule
is a class which implements Centeron\Permissions\Contracts
and has only one method handle
.
If this method returns true
then permission/role AuthItem
will enable, if false
, the current permission will be ignored.
As examples this package provides 3 rules out of the box:
Access for permission authItem
is available only on weekdays:
User only has access to own objects that he has created:
In this case we have to provide information about the object (ID) as a parameter.
User has access only to certain categories that have been listed in a database:
In this case we have to provide information about categories as parameters.
Also, information about categories with conditional access must be saved in the data
field of the table.
Apparently each of users can be associated with a certain list of categories. In such situations you shoudn't create
new AuthItem
with specific data
and the same rule
for each user. Rather, you can save data in a foreign table
and provide this data to the class as parameteres along with other information.
We perform admission checks on conditional permissions not via methods hasAnyAuthItems
and hasAllAuthItems
, but
with canAnyAuthItems
and canAnyAuthItems
, which require only 2 parameters. e first parameter is role/permission or
an array of roles/permissions, and the second is an array of variables:
Also you can determine via trait method canAuthItems
which permissions are attached to user from the passed list.
The Blade directives work according these rules. The same is true of authorize
method and Gate
methods.
Split of access among users by parameters
The field base_auth_id
in AuthItem
can be empty. It can be used to connect with otherAuthItem
,
which is a base item. Methods canAuthItems
, canAnyAuthItems
, canAllAuthItems
check access
not only using given permissions (and their inheritances), but also considering base_auth_id
permisssions.
Let's have a look on the case when users have to have accesses to only own folders in a file manager. The permission which is responsible
for the a access is AuthItem
with ID=1
and name Folder View
. All what we need to do is to create new permissions AuthItem
for
each of users with folder names in the data
-field and rule-handler in the rule
-field. Set 1
in base_auth_id
-field (ID Folder View
)
When user try to access a folder folder_name
via $user->canAnyAuthItems(['Folder View'], ['folder_name']);
not only the check Folder View
will be made, but checking other permissions as well with base_auth_id = 1
, matching
folder_name
with data
of AuthItem
applying rule
.
Cache
In spite of a relatively large number of database request (from 3 to 5, depending of situation) access checking performs quickly due to the simplicity of these requests to the database(select from the indexed columns of tables). Cache gets and saves data of each tables.
Any changing of tables by the provided RBAC methods will reset the cache. You may also reset the cache manually:
Enable/disable cache, set the cache lifetime, its identifier you can by editing config/permissions.php
.
Beware! In cases where the application has hundreds or thousands of roles and permisssions and their relations to users, the amount of used memory sometimes increases enormously because the information from all tablesis cached. But processing time stays about the same. Working with a disabled cache doesn't require a big amount of memory even with thousands of records in database tables because the requests are only linked with relevant data necessary for the current checking
Database structure
To implement all work, Laravel RBAC needs only 3 database tables:
auth_items
- roles and permissionsauth_item_childs
- inheritance of roles and permissionsauth_assignments
- assignments roles/permissions and models
Table names can be changed in config/permissions.php
before running the migration.