Download the PHP package damiantw/laravel-roles without Composer

Role Based Authorization For Laravel 6

1. Purpose
2. Concept
3. Installation
4. Usage
   • Middleware
     • Route Middleware
     • Controller Middleware
   • API
   • Seeding RoleGroups
     • Controller Based RoleGroup Seeding
   • Blade Directives

Purpose

This package aims to provide a granular, clearly defined and easily accessible authority set for association with the Laravel User model. Out of the box Laravel offers some very [powerful tools](https://laravel.com/docs/6.x/authorization "Laravel 6.x Authorization Docs") for handling checks on whether a user can complete a certain action. Often the determining factor is the result of a simple boolean calculation (ex. does the id of a user match the user_id of the Post being edited?). A User's defined authority set can easily be factored into these calculations to provide a protection front using the provided API. We can then only allow users with the correct authorities access to actions using the Laravel Authorization tools or the provided Middleware.

Concept

Each user in the application has a defined authority set. An authority is nothing more then a unique string that hints at a permitted action or a level of privilege. Authorities live inside Roles, with each Role holding exactly one authority value. Roles can be associated with specific Users or with any number of RoleGroups. RoleGroups provide a way to define a common set of authorities that can be shared by many users. A User can be associated with many RoleGroups.

A user's final defined authorities consists of the set of authorities from the Roles directly associated with the user merged with all of the authorities associated with a User's RoleGroups. This approach allows for the flexibility to handle special case scenarios (such as needing to offer a specific lower privileged User access to single administrative action.) while providing the convenience of common assignable authority sets.

Installation

Install via Composer

composer require DamianTW/laravel-roles

Next add the ServiceProvider to the Package Service Providers in config/app.php

Add the HoldsAuthorities traits to the User model

If you plan to make use of the hasAuthority or hasAuthorityController Middleware you will need to add them to your $routeMiddleware array in app/Http/Kernel.php

Running php artisan vendor:publish will install the role configuration file, database migrations, Role/RoleGroup Eloquent models and RoleGroupsTableSeeder boilerplate to your application. At the very minimum you should install the migrations and Eloquent models with: php artisan vendor:publish --tag=migrations --tag=models.

Now just run the migrations =) php artisan migrate

Usage

A User's authority set pairs nicely with Laravel's built in authorization tools such as Policies.

For example lets make a policy for a Post model:

We can then query a User's authority set within our Policy methods. This creates a front protection that ensures a User has the authority to participate in this action at all. We can then provide additional logic to determine if this specific instance of the action should be allowed.

After registering our policy in the AuthServiceProvider, our PostController can make use of the authorize() Controller helper. If the Policy check does not pass an Illuminate\Auth\Access\AuthorizationException will be thrown causing the default Laravel exception handler to issue a HTTP 403 status code as the response.

Middleware

Creating a Policy for certain actions may seem unnecessary if the only requirement to complete the actions is to hold a certain a authority(ies). For these situations you can make use of the provided hasAuthority and hasAuthorityController Middleware.

Route Middleware

Individual routes can be protected by applying the hasAuthority Middleware. If the user does not have the required authority(ies) for a route an Symfony\Component\HttpKernel\Exception\HttpException will be thrown with a status code of 401.

Controller Middleware

You can easily protect all actions in a Controller by applying the hasAuthorityController Middleware in the Controller's constructor. When a User attempts to access a route for any of the Controller's actions they will be checked for a role following the convention CONTROLLERSUBJECT_METHOD. If the user does not have the required authority for a route an Symfony\Component\HttpKernel\Exception\HttpException will be thrown with a status code of 401.

Take the following Controller for example:

Each route will be checked with an authority.

API

The HoldsAuthorities Trait adds the following methods to the User model

Seeding RoleGroups

You may want to provide a default set of RoleGroups with specific authorities for your application. This is a good use case for Laravel's seeding features.

This package provides a RoleGroupsTableSeeder boilerplate and a RoleGroupSeeder Facade which can be used to clearly define the default authority sets for your application's RoleGroups.

When we run php arisian db:seed --class=RoleGroupsTableSeeder the RoleGroupSeeder Facade will automatically create Roles for authorities that do not already exist and sync the RoleGroup authority set definitions as you defined them.

If your application does not allow for changing RoleGroup authority set definitions at runtime it can be useful to run this command as part of the deployment procedure.

Controller Based RoleGroup Seeding

You can also pass Controller classes as part of the RoleGroup authority definition. RoleGroupSeeder will create an authority for each public, non magic method in the controller following the convention CONTROLLERSUBJECT_METHOD.

Take the following Controller for example:

when PostController is passed as part of the definition:

Authorities with the following roles will be created and associated with the group:

• NON_CONTROLLER_BASED_AUTHORITY
• POST_CREATE
• POST_STORE
• POST_SHOW
• POST_EDIT
• POST_UPDATE
• POST_DESTROY

Blade Directives

The following directives are available in Blade views for convenience and code readability.

Disclaimer

This package has only been tested with Laravel 6.12.0, though everything should work with Laravel 6.*.

Wish List

• Cache User authority set
• hasAuthority Blade directive
• Protect all of a controllers actions automatically using a convention
• Tests