Download the PHP package szykra/laravel-guard without Composer

Laravel Guard

Simple and easy to use roles and permissions system (ACL) for Laravel 5.

Laravel Guard is package to easy controlling access to parts of your system. It provides simple tool to protect your routes and user methods to checking permissions.

Installation

Install via composer

Add dependency to your composer.json file and run composer update.

Configuration

Make new migration to store roles and permissions

Currently Guard stores all information about roles and permissions in database.

Of course you should add new field to your users table to link user with role.

Configure your User model

Guard provides new contract - Permissible. It requires two methods:

• is($role)
• can($action)

Don't worry! Guard has trait which implements these methods. The only thing you have to do is use it and add new relationship to roles.

User model

Guard provides two new models to your application - Role and Permission. Don't worry about them - they are needed to retrieve information from database.

Add service provider to your config

Open your config/app.php file and add this line to $providers array

Now Permissible interface is binding to currently logged user. You can inject it everywhere you need by IoC Container but remember - if you are not logged in then application throws binding exception. Always use this interface with auth middleware!

Register new middleware

Open your app/Http/Kernel.php and add this line to $middleware array

If you don't want to protect all routes you can register this middleware as $routeMiddleware and use it only in specific routes.

Roles and permissions

Guard provides management for Roles and Permissions but what exactly does that mean?

In complex system we have a lot types of users, e.g. Administrators, Managers, Users or Moderators. This types are called roles. Users can perform a lot of actions at the system but specific types of users should have specified rights called permissions. When a user has a role, also has permissions that depend on his role. We can check these permissions to prevent or allow specific actions.

Permission naming convention

Guard does not defined how you should name your permissions. Try to keep it simple, short, consistent and easy to remember. I really like use a simple notation RESOURCE.ACTION, e.g. USERS.READ, USERS.UPDATE. Feel free to use own naming convention, e.g. read users, update user. The choice is yours!

Creating Roles and Permissions

You have a lot of possibilities to create Roles or Permissions. You can manually insert data to database, create special Seeder to prepare data or use artisan Guard commands to create Role and Permission entries on demand.

Create using Artisan CLI

Guard provides new artisan commands:

• guard:grant role permission
• guard:make:role tag [name]
• guard:make:permission tag [name]

To create new role run below command:

Create new permission

To create permission and instantly link it with role use --role option

To link existing role with permission use guard:grant command

Create using Seeder

If you have a lot of roles and permissions then seeder is a good choice, e.g.

Usage

Route protection

To protect your route define key needs in route array

You can require more permissions for single route:

If you are define Guard as $routeMiddleware you must add middleware action:

Of course you can group your routes with required permissions:

Checking permissions

You have two new methods in user model to checking permissions.

• $user->can($action)
• $user->is($role)

To get user instance use Laravel Auth facade or inject instance of Permissible into your class.

Inject to constuctor

Inject to action

Retrieve user by Auth facade

You can check permissions wherever you have instance of current authenticated user, e.g. by Auth::user(). It's very useful in views, when you have to render a part of view only for users with specific permissions.

Checking permissions in Form Request

Laravel 5 Form Requests are very nice places to checking permissions. See below example.

Reaction when user has not enough permissions

If user has not enough permissions then Guard thrown InsufficientPermissionException. You can catch it and return view, redirect or something else.

To catch this exception globally use your ExceptionHandler, e.g. app/Exception/Handler.php, method render()

License

The MIT License. Copyright © 2015 Szymon Krajewski.