Download the PHP package cgross/laraguard without Composer

Laraguard WIP

Adds a permission system to Laravel 5 using the new integrated authentication mechanism. Instead of protecting routes, it protects the controller and its methods. This way you do not expose protected functionality if you forgot to protect a certain route. Controllers are protected with a simple syntax: ControllerName@MethodName. If you have a ClientController.php and want to add a permission called client.edit you would do something like this:

Laraguard also supports * if you want to allow all methods or all controllers:

Installation

Composer:

Integrate this into your laravel projects composer.json and execute composer update:

Add middleware:

Add this line to the $routeMiddleware array in app/Http/Kernel.php:

Protect controllers:

For every controller that you want to protect from unauthorized access call the laraguard middleware in the constructor like this:

Extend the User model:

Extend the User model with a method getPermissions which returns an array with the users permissions. You might also want to extend the user schema to save permissions in the database. If Laraguard is not flexible enough for your needs you can create a new database table for user roles which then references permissions assigned to those roles. Implement it like you want, just make sure the getPermissions method exists in the User model and that it returns an array with permission names. Take a look at https://github.com/caffeinated/shinobi or https://github.com/romanbican/roles which both allow you to store roles and permissions for your users. Then adapt the getPermissions method in your user model to retrieve the permissions from caffeinated/shinobi or romanbican/roles.

Permissions

Create an new file resources/config/permissions.yml with the following content, adapted to your needs:

Note: The default permission for users that are not logged in is guest.

What happens when the user or guest has no permission?

If the user has no permission for the desired controller method then there are three possibilities:

1. The controller has a method named permissionDenied. In this case the method is called. This gives you the ability to display custom permission denied views for different controllers or redirect to some other page
2. The value defaultNoPermissionRoute in permissions.yml is not NONE. In this case the request is redirected to this route
3. Neither a permissionDenied nor a defaultNoPermissionRoute is set: In this case the response will be a 501 Permission Denied error page.

Testing

When testing an app you might want to set some defaultPermissions for testing mode. Those permissions will only work if you test with the same APP_ENV that is specified in appEnv. You can do this with the following entries in permissions.yml:

If you want to set different Permission for different testcases then you need to add the LaraguardServiceProvider in config/app.php:

After that you can get a Laraguard instance from the IoC Container:

Behat

If you are using Behat then try the Laraguard trait:

This trait will automatically clear all temporary permissions after each scenario and if you need you can use self::$laraguard in your tests to set or reset permissions. In your behat features you will have the following new expressions available:

Debugging

You can now enabled debugging in your permissions.yml. This will print debug output to your laravel log (usually in storage/log/laravel-YYYY-MM-DD.log).

Redirect after login / get last denied page

Laraguard stores the path of the last denied page in a session var (laraguard_lastDenied). This session var will be cleared after X requests (default is two requests). You can change this under deniedUrlLifetime in your permissions.yml.

Add a login form to your denied page. To redirect a user after login, modify the redirectPath method of your AuthController:

Changelog

1.1.0:

• Store last denied url to make a redirect after login feature possible
• Give access to testing permissions getTemporaryPermissions()

1.0.0:

• Added testing capabilities
• Support for Behat
• Added debugging (see permission.yml in README)

0.1.0: Initial release

Breaking changes

Version v1.0.0 changed modelActionPermissions to controllerActionPermissions in permissions.yml.