Laratrust

Docs

Table of Contents
Introduction

Installation

Configuration

After Installation

2.1

Models

2.2

Role

2.2.1

Permission

2.2.2

User

2.2.3

Seeder (Optional)
Usage

2.3
3

Concepts

3.1

Soft Deleting

3.2

Blade templates

3.3

Middleware

3.4

Short syntax route filter

3.5

Route filter

3.6

Troubleshooting

License

Contribution guidelines

Laratrust Docs

Table of Contents
Please read all the sections in order
Introduction
Installation
Configuration
After Installation
Models
Role
Permission
User
Seeder (Optional)
Usage
Concepts
Soft Deleting
Blade templates
Middleware
Short syntax route filter
Route filter
Troubleshooting
License
Contribution guidelines

Introduction

Laratrust Docs

Installation
1) In order to install Laravel 5 Laratrust, just add the following to your composer.json. Then
run composer update :
"santigarcor/laratrust": "3.0.*"

or you can run the composer require command from your terminal:
composer require "santigarcor/laratrust:3.0.*"

2) Then in your config/app.php add the following to the providers array:

Laratrust\LaratrustServiceProvider::class,

3) In the same config/app.php and add the following to the aliases array:
'Laratrust' => Laratrust\LaratrustFacade::class,

4) If you are going to use Middleware (requires Laravel 5.1 or later) you also need to add the
following to routeMiddleware array in app/Http/Kernel.php .
'role' => \Laratrust\Middleware\LaratrustRole::class,
'permission' => \Laratrust\Middleware\LaratrustPermission::class,
'ability' => \Laratrust\Middleware\LaratrustAbility::class,

Installation

Laratrust Docs

After Installation
Configuration Files
Set the property values in the config/auth.php . These values will be used by laratrust to
refer to the correct user model.
You can also publish the configuration for this package to further customize table names and
model namespaces.
Just use php artisan vendor:publish and a laratrust.php file will be created in your
app/config directory.

Automatic setup (Recommended)

If you want to let laratrust to setup by itselft, just run the following command:
php artisan laratrust:setup

This command will generate the migrations, create the Role and Permission models and
will add the trait to the User model.
The user trait will be added to the Model configured in the auth.php file.
And then don't forget to run:
composer dump-autoload

If you did the steps above you are done with the
configuration, if not, please read and follow the whole
configuration process

Migrations
Now generate the Laratrust migration:
php artisan laratrust:migration

After Installation

Laratrust Docs

It will generate the <timestamp>_laratrust_setup_tables.php migration. You may now run it

with the artisan migrate command:
php artisan migrate

After the migration, four new tables will be present:

roles stores role records
permissions stores permission records
role_user stores many-to-many relations between roles and users
permission_role stores many-to-many relations between roles and permissions

After Installation

Laratrust Docs

Role
Create a Role model inside app/models/Role.php using the following example:
<?php namespace App;
use Laratrust\LaratrustRole;
class Role extends LaratrustRole
{
}

The Role model has three main attributes:

name Unique name for the Role, used for looking up role information in the

application layer. For example: "admin", "owner", "employee".

display_name Human readable name for the Role. Not necessarily unique and

optional. For example: "User Administrator", "Project Owner", "Widget Co. Employee".
description A more detailed explanation of what the Role does. Also optional.

Both display_name and description are optional; their fields are nullable in the database.

Role

Laratrust Docs

Permission
Create a Permission model inside app/models/Permission.php using the following example:
<?php namespace App;
use Laratrust\LaratrustPermission;
class Permission extends LaratrustPermission
{
}

The Permission model has the same three attributes as the Role :
name Unique name for the permission, used for looking up permission information in

the application layer. For example: "create-post", "edit-user", "post-payment", "mailinglist-subscribe".

display_name Human readable name for the permission. Not necessarily unique and

optional. For example "Create Posts", "Edit Users", "Post Payments", "Subscribe to
mailing list".
description A more detailed explanation of the Permission.

In general, it may be helpful to think of the last two attributes in the form of a sentence: "The
permission display_name allows a user to description ."

Permission

Laratrust Docs

User
Next, use the LaratrustUserTrait trait in your existing User model. For example:
<?php
use Laratrust\Traits\LaratrustUserTrait;
class User extends Model
{
use LaratrustUserTrait; // add this trait to your user model
...
}

This will enable the relation with Role and add the following methods roles() ,
hasRole($name) , can($permission) , and ability($roles, $permissions, $options) within

your User model.

Don't forget to dump composer autoload
composer dump-autoload

At this point you are ready to go.

User

Laratrust Docs

Seeder
Laratrust comes with a database seeder, this seeder helps you filling the permissions for
each role depending on the module, and creates one user for each role.
To generate the seeder you have to run:
php artisan laratrust:seeder

and
composer dump-autoload

And in the database/seeds/DatabaseSeeder.php file you have to add to the run method:
$this->call(LaratrustSeeder::class);

If you haven't run php artisan vendor:publish you should run it in order to customize
the roles, modules and permissions in each case.
After you run php artisan vendor:publish , you will have a config/laratrust_seeder.php file
and it looks like this:
return [
'role_structure' => [
'superadministrator' => [
'users' => 'c,r,u,d',
'acl' => 'c,r,u,d',
'profile' => 'r,u'
],
'administrator' => [
'users' => 'c,r,u,d',
'profile' => 'r,u'
],
'user' => [
'profile' => 'r,u'
],
],
...
];

To understand the file you must know:

Seeder (Optional)

Laratrust Docs

The first level is the roles.

The second level is the modules.
The second level assignments are the permissions.
With that in mind, you should arrange your roles, modules and permissions like this:
return [
'role' => [
'module' => 'permissions',
],
];

Permissions
In case that you don't want to use the c,r,u,d permissions, in the
config/laratrust_seeder.php there the permissions_map where you can change the

permissions mapping.

Seeder (Optional)

10

Laratrust Docs

Concepts
Let's start by creating the following Role s and Permission s:
$owner = new Role();
$owner->name = 'owner';
$owner->display_name = 'Project Owner'; // optional
$owner->description = 'User is the owner of a given project'; // optional
$owner->save();
$admin = new Role();
$admin->name = 'admin';
$admin->display_name = 'User Administrator'; // optional
$admin->description = 'User is allowed to manage and edit other users'; // optional
$admin->save();

Next, with both roles created let's assign them to the users. Thanks to the HasRole trait this
is as easy as:
$user = User::where('username', '=', 'michele')->first();
// role attach alias
$user->attachRole($admin); // parameter can be an Role object, array, or id
// or eloquent's original technique
$user->roles()->attach($admin->id); // id only

Now we just need to add permissions to those Roles:

Concepts

11

Laratrust Docs

$createPost = new Permission();

$createPost->name = 'create-post';
$createPost->display_name = 'Create Posts'; // optional
// Allow a user to...
$createPost->description = 'create new blog posts'; // optional
$createPost->save();
$editUser = new Permission();
$editUser->name = 'edit-user';
$editUser->display_name = 'Edit Users'; // optional
// Allow a user to...
$editUser->description = 'edit existing users'; // optional
$editUser->save();
$admin->attachPermission($createPost);
// equivalent to $admin->perms()->sync([$createPost->id]);
$owner->attachPermissions([$createPost, $editUser]);
// equivalent to $owner->perms()->sync([$createPost->id, $editUser->id]);

Checking for Roles & Permissions

Now we can check for roles and permissions simply by doing:
$user->hasRole('owner'); // false
$user->hasRole('admin'); // true
$user->can('edit-user'); // false
$user->can('create-post'); // true

Both hasRole() and can() can receive an array of roles & permissions to check:
$user->hasRole(['owner', 'admin']); // true
$user->can(['edit-user', 'create-post']); // true

By default, if any of the roles or permissions are present for a user then the method will
return true. Passing true as a second parameter instructs the method to require all of the
items:
$user->hasRole(['owner', 'admin']); // true
$user->hasRole(['owner', 'admin'], true); // false, user does not have admin role
$user->can(['edit-user', 'create-post']); // true
$user->can(['edit-user', 'create-post'], true); // false, user does not have edit-user permission

You can have as many Role s as you want for each User and vice versa.
Concepts

12

Laratrust Docs

The Laratrust class has shortcuts to both can() and hasRole() for the currently logged
in user:
Laratrust::hasRole('role-name');
Laratrust::can('permission-name');
// is identical to
Auth::user()->hasRole('role-name');
Auth::user()->can('permission-name);

You can also use placeholders (wildcards) to check any matching permission by doing:
// match any admin permission
$user->can("admin.*"); // true
// match any permission about users
$user->can("*_users"); // true

User ability
More advanced checking can be done using the awesome ability function. It takes in
three parameters (roles, permissions, options):
roles is a set of roles to check.
permissions is a set of permissions to check.

Either of the roles or permissions variable can be a comma separated string or array:
$user->ability(['admin', 'owner'], ['create-post', 'edit-user']);
// or
$user->ability('admin,owner', 'create-post,edit-user');

This will check whether the user has any of the provided roles and permissions. In this case
it will return true since the user is an admin and has the create-post permission.
The third parameter is an options array:
$options = [
'validate_all' => true | false (Default: false),
'return_type' => boolean | array | both (Default: boolean)
];

Concepts

13

Laratrust Docs

validate_all is a boolean flag to set whether to check all the values for true, or to

return true if at least one role or permission is matched.

return_type specifies whether to return a boolean, array of checked values, or both in

an array.
Here is an example output:
$options = [
'validate_all' => true,
'return_type' => 'both'
];
list($validate, $allValidations) = $user->ability(
['admin', 'owner'],
['create-post', 'edit-user'],
$options
);
var_dump($validate);
// bool(false)
var_dump($allValidations);
// array(4) {
// ['role'] => bool(true)
// ['role_2'] => bool(false)
// ['create-post'] => bool(true)
// ['edit-user'] => bool(false)
// }

The Laratrust class has a shortcut to ability() for the currently logged in user:
Laratrust::ability('admin,owner', 'create-post,edit-user');
// is identical to
Auth::user()->ability('admin,owner', 'create-post,edit-user');

Concepts

14

Laratrust Docs

Soft Deleting
The default migration takes advantage of onDelete('cascade') clauses within the pivot
tables to remove relations when a parent record is deleted. If for some reason you cannot
use cascading deletes in your database, the LaratrustRole and LaratrustPermission classes,
and the HasRole trait include event listeners to manually delete records in relevant pivot
tables. In the interest of not accidentally deleting data, the event listeners will not delete
pivot data if the model uses soft deleting. However, due to limitations in Laravel's event
listeners, there is no way to distinguish between a call to delete() versus a call to
forceDelete() . For this reason, before you force delete a model, you must manually

delete any of the relationship data (unless your pivot tables uses cascading deletes). For
example:
$role = Role::findOrFail(1); // Pull back a given role
// Regular Delete
$role->delete(); // This will work no matter what
// Force Delete
$role->users()->sync([]); // Delete relationship data
$role->perms()->sync([]); // Delete relationship data

$role->forceDelete(); // Now force delete will work regardless of whether the pivot table has cascadi

Soft Deleting

15

Laratrust Docs

Blade templates
Three directives are available for use within your Blade templates. What you give as the
directive arguments will be directly passed to the corresponding Laratrust function.
@role('admin')
<p>This is visible to users with the admin role. Gets translated to
\Laratrust::role('admin')</p>
@endrole
@permission('manage-admins')
<p>This is visible to users with the given permissions. Gets translated to
\Laratrust::can('manage-admins'). The @can directive is already taken by core
laravel authorization package, hence the @permission directive instead.</p>
@endpermission
@ability('admin,owner', 'create-post,edit-user')
<p>This is visible to users with the given abilities. Gets translated to
\Laratrust::ability('admin,owner', 'create-post,edit-user')</p>
@endability

Blade templates

16

Laratrust Docs

Middleware
You can use a middleware to filter routes and route groups by permission or role
Route::group(['prefix' => 'admin', 'middleware' => ['role:admin']], function() {
Route::get('/', 'AdminController@welcome');

Route::get('/manage', ['middleware' => ['permission:manage-admins'], 'uses' => 'AdminController@m

});

It is possible to use pipe symbol as OR operator:

'middleware' => ['role:admin|root']

To emulate AND functionality just use multiple instances of middleware

'middleware' => ['role:owner', 'role:writer']

For more complex situations use ability middleware which accepts 3 parameters: roles,
permissions, validate_all
'middleware' => ['ability:admin|owner,create-post|edit-user,true']

Middleware

17

Laratrust Docs

Short syntax route filter

To filter a route by permission or role you can call the following in your app/Http/routes.php :

// only users with roles that have the 'manage_posts' permission will be able to access any route wit
Laratrust::routeNeedsPermission('admin/post*', 'create-post');
// only owners will have access to routes within admin/advanced
Laratrust::routeNeedsRole('admin/advanced*', 'owner');
// optionally the second parameter can be an array of permissions or roles
// user would need to match all roles or permissions for that route
Laratrust::routeNeedsPermission('admin/post*', array('create-post', 'edit-comment'));
Laratrust::routeNeedsRole('admin/advanced*', array('owner','writer'));

Both of these methods accept a third parameter. If the third parameter is null then the return
of a prohibited access will be App::abort(403) , otherwise the third parameter will be
returned. So you can use it like:
Laratrust::routeNeedsRole('admin/advanced*', 'owner', Redirect::to('/home'));

Furthermore both of these methods accept a fourth parameter. It defaults to true and checks
all roles/permissions given. If you set it to false, the function will only fail if all
roles/permissions fail for that user. Useful for admin applications where you want to allow
access for multiple groups.
// if a user has 'create-post', 'edit-comment', or both they will have access
Laratrust::routeNeedsPermission('admin/post*', array('create-post', 'edit-comment'), null
// if a user is a member of 'owner', 'writer', or both they will have access
Laratrust::routeNeedsRole('admin/advanced*', array('owner','writer'), null, false);

// if a user is a member of 'owner', 'writer', or both, or user has 'create-post', 'edit-comment' the
// if the 4th parameter is true then the user must be a member of Role and must have Permission
Laratrust::routeNeedsRoleOrPermission(
'admin/advanced*',
array('owner', 'writer'),
array('create-post', 'edit-comment'),
null,
false
);

Short syntax route filter

18

Laratrust Docs

Short syntax route filter

19

Laratrust Docs

Route filter
Laratrust roles/permissions can be used in filters by simply using the can and hasRole
methods from within the Facade:
Route::filter('manage_posts', function()
{
// check the current user
if (!Laratrust::can('create-post')) {
return Redirect::to('admin');
}
});

// only users with roles that have the 'manage_posts' permission will be able to access any admin/pos
Route::when('admin/post*', 'manage_posts');

Using a filter to check for a role:

Route::filter('owner_role', function()
{
// check the current user
if (!Laratrust::hasRole('Owner')) {
App::abort(403);
}
});
// only owners will have access to routes within admin/advanced
Route::when('admin/advanced*', 'owner_role');

As you can see Laratrust::hasRole() and Laratrust::can() checks if the user is logged
in, and then if he or she has the role or permission. If the user is not logged the return will
also be false .

Route filter

20

Laratrust Docs

Troubleshooting
If you encounter an error when doing the migration that looks like:

SQLSTATE[HY000]: General error: 1005 Can't create table 'laravelbootstrapstarter.#sql-42c_f8' (errno:

(SQL: alter table `role_user` add constraint role_user_user_id_foreign foreign key (`user_id`)
references `users` (`id`)) (Bindings: array ())

Then it's likely that the id column in your user table does not match the user_id column
in role_user . Make sure both are INT(10) .

When trying to use the LaratrustUserTrait methods, you encounter the error which looks like
Class name must be a valid object or a string

then probably you don't have published Laratrust assets or something went wrong when you
did it. First of all check that you have the laratrust.php file in your app/config directory. If
you don't, then try php artisan vendor:publish and, if it does not appear, manually copy the
/vendor/santigarcor/laratrust/src/config/config.php file in your config directory and

rename it laratrust.php .

Troubleshooting

21

Laratrust Docs

License
Laratrust is free software distributed under the terms of the MIT license.

License

22

Laratrust Docs

Contribution guidelines
Support follows PSR-1 and PSR-4 PHP coding standards, and semantic versioning.
Additionally the source code follows the PSR-2 code style and the builds check it.
Please report any issue you find in the issues page.
Pull requests are welcome.

Contribution guidelines

23