Download the PHP package centeron/laravel-roles-permissions without Composer

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 logic
• data - 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 permissions
• auth_item_childs - inheritance of roles and permissions
• auth_assignments - assignments roles/permissions and models

Table names can be changed in config/permissions.php before running the migration.