Download the PHP package shanmuga/laravel-entrust without Composer

Laravel Entrust (Supports Laravel 5 to 10)

Handle Role-based Permissions for your Laravel application.

Version Compatibility

Contents

• Installation & Configuration
• Usage
  • Concepts
    • Checking for Roles & Permissions
    • User ability
  • Middleware
• Troubleshooting
• License
• Contribution guidelines
• Additional information

Installation

1) You can install the Laravel-entrust package via composer:

Note: You Can Skip step 2 and 3 If you are using above Laravel 5.5.

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

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

4) Run the command below to publish the package config files config/entrust.php and config/entrust_seeder.php

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

Name of the migration file to be generated

Model and Table Used for Authorization

Name of the Models Used for Role and Permission

Default Guard to perform user authentication, You Can also pass it manually when checking it.

You can also use multiple guards:

Table names used for roles and permissions

Foriegn keys used for roles and permissions

Middleware Setup for custom message, register set to true for register automatically, Handling is which handler to be used either abort or redirect. you can also configure what message should be display if authorization failed.

6) Run the following command to generate migration and seed

See Entrust Seeder Configuration to learn more about create permissions.

7) Finally Add the LaravelEntrustUserTrait to existing User model. For example:

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

Don't forget to dump composer 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:

Usage

Concepts

Let's start by configuring entrust_seeder to create role and permissions: Your config/laratrust_seeder.php file looks like this:

Now Users are created and alse roles and it's permissions are assigned to that users. You Can also attach and detach role is as easy as:

Checking for Roles & Permissions

Now we can check for roles and permissions simply by doing:

Both hasRole() and hasPermission() can receive an array of roles & permissions to check:

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:

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:

You can also use placeholders (wildcards) to check any matching permission by doing:

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:

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-user permission.

The third parameter validateAll 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. It is optional and by default it is false.

Middleware

You can use a middleware to filter routes and route groups by permission or role

It is possible to use pipe symbol as OR operator:

To emulate AND functionality just use multiple instances of middleware

Troubleshooting

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

This occur when use laravel less than 5.8. It uses Integer for migration autoIncrement but laravel entrust uses BigInteger. So make sure both are same..

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 --tag=LaravelEntrust and, if it does not appear, manually copy the /vendor/shanmuga/laravel-entrust/src/config/entrust.php file in your config directory.

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

License

Laravel-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 always welcome.