Configuration Files¶

Set the proper values in the config/auth.php. These values will be used by laratrust to refer to the user model.

You can also publish the configuration for this package to further customize table names and model namespaces.

Use php artisan vendor:publish, the laratrust.php and laratrust_seeder.php files 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.

And then do not forget to run:

composer dump-autoload

Migrations¶

Now generate the Laratrust migration:

php artisan laratrust:migration

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

Permissions¶

In case that you do not 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.

Set things up¶

Let’s start by creating the following Roles:

$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();

Now we just need to add Permissions to those Roles:

$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();

Permissions Assignment & Removal¶

By using the LaratrustRoleTrait we can do the following:

$admin->attachPermission($createPost);
// equivalent to $admin->permissions()->attach([$createPost->id]);

$owner->attachPermissions([$createPost, $editUser]);
// equivalent to $owner->permissions()->attach([$createPost->id, $editUser->id]);

$owner->savePermissions([$createPost, $editUser]);
// equivalent to $owner->permissions()->sync([$createPost->id, $editUser->id]);

$admin->detachPermission($createPost);
// equivalent to $admin->permissions()->detach([$createPost->id]);

$owner->detachPermissions([$createPost, $editUser]);
// equivalent to $owner->permissions()->detach([$createPost->id, $editUser->id]);

Roles Assignment & Removal¶

With both roles created let’s assign them to the users. Thanks to the LaratrustUserTrait this is as easy as:

$user->attachRole($admin); // parameter can be an Role object, array, or id
// equivalent to $user->roles()->attach([$admin->id]);

$user->attachRoles([$admin, $owner]); // parameter can be an Role object, array, or id
// equivalent to $user->roles()->attach([$admin->id, $owner->id]);

$user->syncRoles([$admin->id, $owner->id]);
// equivalent to $user->roles()->sync([$admin->id]);

$user->detachRole($admin); // parameter can be an Role object, array, or id
// equivalent to $user->roles()->detach([$admin->id]);

$user->detachRoles([$admin, $owner]); // parameter can be an Role object, array, or id
// equivalent to $user->roles()->detach([$admin->id, $owner->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 Roles as you want for each User and vice versa.

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.
• options is a set of options to change the method behavior.

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)
];

• 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');

Model’s Ownership¶

If you need to check if the user owns a model you can use the user function owns:

public function update (Post $post) {
   if ($user->owns($post)) { //This will check the 'user_id' inside the $post
      abort(403);
   }

   ...
}

If you want to change the foreign key name to check for, you can pass a second attribute to the method:

public function update (Post $post) {
   if ($user->owns($post, 'idUser')) { //This will check for 'idUser' inside the $post
      abort(403);
   }

   ...
}

...

Concepts¶

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@manageAdmins']);
});

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 Return¶

The middleware supports two kinds of returns in case the check fails. You can configure the return type and the value in the config/laratrust.php file.

'middleware_handling' => 'redirect',
'middleware_params'   => '/home',       // Change this to the route you need