Download the PHP package directorytree/authorization without Composer

An easy, native role / permission management system for Laravel.

Index

• Installation
  • Migration Customization
  • Model Customization
• Usage
• Checking Permissions & Roles
• Caching
• Gate Registration
• Middleware
• Testing

Installation

To get started, install Authorization via the Composer package manager:

composer require directorytree/authorization

The Authorization service provider registers its own database migration directory with the framework, so you should migrate your database after installing the package. The Authorization migrations will create the tables your application needs to store roles and permissions:

php artisan migrate

Now insert the DirectoryTree\Authorization\Traits\Authorizable onto your App\Models\User model:

You can now perform user authorization.

Migration Customization

If you would not like to use Authorization's default migrations, you should call the Authorization::ignoreMigrations method in the register method of your AppServiceProvider. You may export the default migrations using php artisan vendor:publish --tag=authorization-migrations.

Model Customization

By default, the App\Models\User class is registered as the authorizable user model.

You're free to extend the models used internally by Authorization, or create your own.

Instruct Authorization to use your own models via the Authorization class in your AuthServiceProvider:

Be sure to add the relevant traits for each of your custom models:

Role Model:

Permission Model:

Usage

Authorization uses native Laravel relationships, so there's no need to learn a new API if you don't want to.

Due to Authorization's trait based implementation, all of Authorization's functionality can be overridden or extended with you own implementation.

Managing Roles & Permissions

Create a permission:

Create a role:

Grant the permission to a role:

Now assign the role to the user:

You may also use the grant() or revoke() method on a Role model:

You may also sync a role's permissions using the grantOnly() method:

You may also detach all permissions from a role using revokeAll():

Managing Users & Permissions

You can also create user specific permissions:

As with roles, may also use the grant() or revoke() method on an authorizable User model:

You may also sync a users' permissions using the grantOnly() method:

Checking Permissions & Roles

Using Laravel's native can() method:

Using Laravel's native authorize() method in your controllers:

Using Laravel's native Gate facade:

Using Laravel's native @can directive in your views:

Checking Permissions & Roles (Using Authorization Package Methods)

Checking for permission:

Checking for multiple permissions:

Checking if the user has any permissions:

Checking if the user has a role:

Checking if the user has specified roles:

Checking if the user has any specified roles:

Caching

By default all permissions are cached to prevent them from being retrieved on every request.

This cache is automatically flushed when permissions are created, updated, or deleted.

If you would like to disable the cache, call Authorization::disablePermissionCache in your AuthServiceProvider:

Cache Key

By default, the permission cache key is authorization.permissions.

To alter the cache key, call Authorization::cacheKey in your AuthServiceProvider:

Cache Expiry

By default, the permission cache will expire daily.

To alter this expiry date, call Authorization::cacheExpiresIn in your AuthServiceProvider:

Gate Registration

By default all permissions you create are registered in Laravel's Gate.

If you would like to disable this, call Authorization::disableGateRegistration in your AuthServiceProvider:

Middleware

Authorization includes two useful middleware classes you can utilize for your routes.

Insert them into your app/Http/Kernel.php:

Once you've added them, you can start using them.

Note: When a user does not meet the requirements using the middleware, a 403 HTTP exception is thrown.

To guard a route to only allow specific permissions:

To guard a route to allow a specific role:

Running Tests

To run your applications tests, you must instantiate the PermissionRegistrar inside your TestCase::setUp() method before running your tests for permissions to register properly: