Are you happy with your logging solution? Would you help us out by taking a 30-second survey? Click here

entrust

Role-based Permissions for Laravel 5

Star full 4f7b624809470f25b6493d5a7b30d9b9cb905931146e785d67c86ef0c205a402Star blank 374f33e4d622a2930833db3cbea26b5d03dc44961a6ecab0b9e13276d97d6682Star blank 374f33e4d622a2930833db3cbea26b5d03dc44961a6ecab0b9e13276d97d6682Star blank 374f33e4d622a2930833db3cbea26b5d03dc44961a6ecab0b9e13276d97d6682Star blank 374f33e4d622a2930833db3cbea26b5d03dc44961a6ecab0b9e13276d97d6682 (1 ratings)
Rated 1.0 out of 5
Subscribe to updates I use entrust


Statistics on entrust

Number of watchers on Github 5578
Number of open issues 391
Average time to close an issue 13 days
Main language PHP
Average time to merge a PR 27 days
Open pull requests 86+
Closed pull requests 44+
Last commit almost 2 years ago
Repo Created over 6 years ago
Repo Last Updated over 1 year ago
Size 443 KB
Organization / Authorzizaco
Latest Release1.7.0
Contributors60
Page Updated
Do you use entrust? Leave a review!
View open issues (391)
View entrust activity
View on github
Fresh, new opensource launches πŸš€πŸš€πŸš€
Trendy new open source projects in your inbox! View examples

Subscribe to our mailing list

Evaluating entrust for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

ENTRUST (Laravel 5 Package)

Build Status Version License Total Downloads

SensioLabsInsight

Entrust is a succinct and flexible way to add Role-based Permissions to Laravel 5.

If you are looking for the Laravel 4 version, take a look Branch 1.0. It contains the latest entrust version for Laravel 4.

Contents

Installation

1) In order to install Laravel 5 Entrust, just add the following to your composer.json. Then run composer update:

"zizaco/entrust": "5.2.x-dev"

2) Open your config/app.php and add the following to the providers array:

Zizaco\Entrust\EntrustServiceProvider::class,

3) In the same config/app.php and add the following to the aliases array:

'Entrust'   => Zizaco\Entrust\EntrustFacade::class,

4) Run the command below to publish the package config file config/entrust.php:

php artisan vendor:publish

5) Open your config/auth.php and add the following to it:

'providers' => [
    'users' => [
        'driver' => 'eloquent',
        'model' => Namespace\Of\Your\User\Model\User::class,
        'table' => 'users',
    ],
],

6) If you want to use Middleware (requires Laravel 5.1 or later) you also need to add the following:

    'role' => \Zizaco\Entrust\Middleware\EntrustRole::class,
    'permission' => \Zizaco\Entrust\Middleware\EntrustPermission::class,
    'ability' => \Zizaco\Entrust\Middleware\EntrustAbility::class,

to routeMiddleware array in app/Http/Kernel.php.

Configuration

Set the property values in the config/auth.php. These values will be used by entrust to refer to the correct user table and model.

To further customize table names and model namespaces, edit the config/entrust.php.

User relation to roles

Now generate the Entrust migration:

php artisan entrust:migration

It will generate the <timestamp>_entrust_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

Models

Role

Create a Role model inside app/models/Role.php using the following example:

<?php namespace App;

use Zizaco\Entrust\EntrustRole;

class Role extends EntrustRole
{
}

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.

Permission

Create a Permission model inside app/models/Permission.php using the following example:

<?php namespace App;

use Zizaco\Entrust\EntrustPermission;

class Permission extends EntrustPermission
{
}

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, mailing-list-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`.

User

Next, use the EntrustUserTrait trait in your existing User model. For example:

<?php

use Zizaco\Entrust\Traits\EntrustUserTrait;

class User extends Eloquent
{
    use EntrustUserTrait; // add this trait to your user model

    ...
}

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

Don't forget to dump composer autoload

composer dump-autoload

And you are ready to go.

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 EntrustRole and EntrustPermission 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 cascading delete

Usage

Concepts

Let's start by creating the following Roles and Permissions:

$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:

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

$owner->attachPermissions(array($createPost, $editUser));
// equivalent to $owner->perms()->sync(array($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 Roles as you want for each User and vice versa.

The Entrust class has shortcuts to both can() and hasRole() for the currently logged in user:

Entrust::hasRole('role-name');
Entrust::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

To filter users according a specific role, you may use withRole() scope, for example to retrieve all admins:

$admins = User::withRole('admin')->get();
// or maybe with a relationsship
$company->users()->withRole('admin')->get();

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(array('admin', 'owner'), array('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 = array(
    '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 = array(
    'validate_all' => true,
    'return_type' => 'both'
);

list($validate, $allValidations) = $user->ability(
    array('admin', 'owner'),
    array('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 Entrust class has a shortcut to ability() for the currently logged in user:

Entrust::ability('admin,owner', 'create-post,edit-user');

// is identical to

Auth::user()->ability('admin,owner', 'create-post,edit-user');

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 Entrust function.

@role('admin')
    <p>This is visible to users with the admin role. Gets translated to 
    \Entrust::role('admin')</p>
@endrole

@permission('manage-admins')
    <p>This is visible to users with the given permissions. Gets translated to 
    \Entrust::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 
    \Entrust::ability('admin,owner', 'create-post,edit-user')</p>
@endability

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@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']

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 within admin/post
Entrust::routeNeedsPermission('admin/post*', 'create-post');

// only owners will have access to routes within admin/advanced
Entrust::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
Entrust::routeNeedsPermission('admin/post*', array('create-post', 'edit-comment'));
Entrust::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:

Entrust::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
Entrust::routeNeedsPermission('admin/post*', array('create-post', 'edit-comment'), null, false);

// if a user is a member of 'owner', 'writer', or both they will have access
Entrust::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' they will have access
// if the 4th parameter is true then the user must be a member of Role and must have Permission
Entrust::routeNeedsRoleOrPermission(
    'admin/advanced*',
    array('owner', 'writer'),
    array('create-post', 'edit-comment'),
    null,
    false
);

Route filter

Entrust 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 (!Entrust::can('create-post')) {
        return Redirect::to('admin');
    }
});

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

Using a filter to check for a role:

Route::filter('owner_role', function()
{
    // check the current user
    if (!Entrust::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 Entrust::hasRole() and Entrust::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.

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: 150)
    (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 EntrustUserTrait 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 Entrust assets or something went wrong when you did it. First of all check that you have the entrust.php file in your config directory. If you don't, then try php artisan vendor:publish and, if it does not appear, manually copy the /vendor/zizaco/entrust/src/config/config.php file in your config directory and rename it entrust.php.

If your app uses a custom namespace then you'll need to tell entrust where your permission and role models are, you can do this by editing the config file in config/entrust.php

'role' => 'Custom\Namespace\Role'
'permission' => 'Custom\Namespace\permission'

License

Entrust is free software distributed under the terms of the MIT license.

Contribution guidelines

Support follows PSR-1 and PSR-4 PHP coding standards, and semantic versioning.

Please report any issue you find in the issues page.
Pull requests are welcome.

entrust open issues Ask a question     (View All Issues)
  • almost 3 years InvalidArgumentException in EntrustUserTrait.php line 176:
  • almost 3 years Avoid simultaneous logins of the same user
  • almost 3 years can entrust support content access control?
  • almost 3 years Is this package going to be maintained?
  • almost 3 years no functionality for @role((!'admin)) ?
  • almost 3 years check role or permission on multi auth
  • almost 3 years displaying user roles
  • almost 3 years When i use @role or @permission in blade laravel will throw β€˜T_CONSTANT_ENCAPSED_STRING’...
  • about 3 years [BadMethodCallException] Call to undefined method Illuminate\Database\Query\Builder::attachRole()
  • about 3 years Minor issue - use vendor publish to publish config file (i.e altering 'role' model namespace)
  • about 3 years BadMethodCallException with message 'This cache store does not support tagging.'
  • about 3 years problem with call the API with token
  • about 3 years 150 "Foreign key constraint is incorrectly formed"
  • about 3 years Error with migration in Laravel 5.1
  • about 3 years Suggestion: UUID
  • about 3 years Funcionando em laravel 5.3?
  • about 3 years Argument 1 passed to Illuminate\Auth\EloquentUserProvider::validateCredentials() must be an instance of Illuminate\Contracts\Auth\Authenticatable, instance of App\User given, called in /home/ubuntu/workspace/vendor/laravel/framework/src/Illuminate/Auth/SessionGuard.php on line 385 and defined
  • about 3 years how to get all permissions?
  • about 3 years {"message":"Unauthenticated.","status_code":500,"debug":
  • about 3 years 'expired_at' doesn't have a default value
  • about 3 years Permission saved on the role tables.
  • about 3 years Filtering View to display only those belongs to user
  • about 3 years Assign role to user type
  • about 3 years User belong to many offices
  • about 3 years Is this support Laravel 5.3?
  • about 3 years Cannot publish migration
  • about 3 years How to implement data limitation for user NOT access page
  • about 3 years Laravel 5.3 blade translation error @role()
  • about 3 years Proper response in middleware
  • about 3 years Undefined class constant 'can'
entrust open pull requests (View All Pulls)
  • Fix readme
  • Laravel 5
  • Fix EntrustRoleTrait
  • Fixed broken migration command
  • Update README.md
  • Removed Still Maintained Image
  • Fix traig use of configuration to match the Laravel 5.2 configuration…
  • Permission foreign key
  • Providers and alias definition became mixed up
  • bindShared() to singleton()
  • Update EntrustRoleTrait.php
  • #422 Do not use unnessary tags for cache
  • Fix model save/delete/restore return values lost
  • use trait booting rather than overriding the entire boot
  • use laravel Event Listeners for clearing cache
  • Refactoring Entrust.php
  • * Cache is now invalidated in more appropriate workflows.
  • Add scopeHasRoles
  • Update file EntrustUserTrait
  • using eager loading for retriving the user and permission set
  • Update EntrustUserTrait.php
  • allow a closure for the result parameter
  • Allow to attach to permission additional validation with parameters
  • hasRole checks for object and id
  • Added support for polymorphic roles and multiple scopes...basically Model ACLs.
  • + detach all permissions
  • Update README.md
  • Added Default Cache Time
  • Add the missing installation steps to the readme
  • Clean up Middleware parameter handling
  • Update MigrationCommand.php
  • Solving Issue: Class name must be a valid object or a string
  • Update README.md
  • Update Readme
  • Make compatible with Lumen for #369.
  • User save method return value
  • Forget quote inside readme file
  • app/config -> config
  • Fixed Config for Laravel 5.2 and later
  • Fix migration error
  • Fix white space
  • fixed MigrationCommand User Table = null
  • Update README.md
  • Create seed_roles_and_permissions_table.php
  • brackets around expression for laravel 5.3
  • Fix for migration missing table name
  • Update EntrustServiceProvider to fix Blade directives
  • fix: savePermissions method add flush cache
  • Fixing blade directives
  • Fix Laravel 5.3 blade issues
  • fixed role blade directive problem on Laravel 5.3
  • Wrap migration in a transaction
  • Update README.md
  • Fixed a typo
  • fix PSR-2 and add missing DocBlocks
  • Fixes Issue #352
  • call to auth.model in boot()
  • Revert "Update EntrustServiceProvider.php"
  • Avoid conflicts with other traits
  • format code
  • Add PHP 7.1 to Travis build
  • Trouble shoot custom namespaces.
  • Allow to pass hasRole() function role object
  • 🎩 use eloquent boot traits method
  • Update EntrustUserTrait.php
  • Fix issue of return status of delete and restore
  • Fixed typo in README.md
  • Update README.md
  • 2.0 dev
  • Dont use cache.ttl, but use entrust.cache_ttl instead
  • Fix 'unknown column' sql error when do operations to permission table, while using a customized tablename
  • Check request is ajax / wants json, if so return json response with 401
  • renamed 'can' method to 'permission' since it is in the laravel core
  • Fixed the soft deleting bug
  • Concentrate test on PHP 7
  • Added @elseifrole and @elserole Blade directives.
  • Update migration.blade.php
  • [Enhancement] Added ability to add individual Permissions to User
  • hotfix UserRole get users config.
  • Use laravel cache key (to allow multiple apps to use the same caching server)
  • Adding model name resolver and user_foreign_key option
  • Use bootTrait() methods instead of generic boot()
  • Update namespace according to psr-4 recommendation
  • Update README.md
  • Set default cache time for cachedRoles method
  • add entrust.cache_ttl config to replace cache.ttl
entrust questions on Stackoverflow (View All Questions)
  • PHP Fatal error: Call to undefined method Illuminate\Foundation\Application::bindShared() in ..Entrust/EntrustServiceProvider.php on line 72
  • Exception when using Entrust middleware in Laravel 5.1
  • Should I use Laravel's Authorization or Zizaco's Entrust?
  • Laravel 5 and Entrust. How to create subscription model based on roles and assignment
  • Eloquent User Where Clause with Entrust Library
  • Laravel 5.1.4 Entrust set up
  • Assign permission to user, not to role using Entrust in Laravel 5
  • Entrust Facade @role not working on Laravel 5.1
  • Need suggestions on using Entrust roles in a single resource controller - Laravel5
  • Install Entrust SSL certificate in Node express application
  • Laravel 5.1 Entrust - Setting up first roles/permissions
  • laravel 4.2 user roles with auth and Entrust
  • Retrieving all users of a specific permission in Laravel 5 / Entrust
  • Laravel 5, Entrust - check roles not working
  • Can Entrust RBAC system store permissions in CODE rather than in DB?
  • How do I compare my Entrust .EPF certificate with a Certificate Revocation List (CRL) file?
  • Laravel Entrust, how to attach existing permission to role
  • How can I authenticate the Zizaco Entrust Role in Frozennode Administrator in Laravel 5?
  • How to setup Eloquent Relationship for Laravel Zizaco/entrust to get Role Permissions?
  • Entrust - Get Permission Based on Role
  • How to add additional Column to Entrust User Role Table?
  • Entrust permission in Laravel
  • Entrust laravel hasRole function was not working
  • Workflow of role/permission based content filtering using Entrust Laravel
  • Find all users with specific Roles in Entrust for Laravel 5
  • Entrust Route Protection in Laravel 5 - Check for Auth first
  • encrypted email with entrust certificate is not opening with MS Outlook
  • How do I get all Users with Roles where role = 'admin' using eloquent along with Entrust?
  • How to assign default user role in entrust?
  • Laravel 5 Entrust one route - load different controller based on Role
entrust list of languages used
More projects by Zizaco View all
Other projects in PHP