Download the PHP package proshore/entrust-lumen without Composer
On this page you can find all versions of the php package proshore/entrust-lumen. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download proshore/entrust-lumen
More information about proshore/entrust-lumen
Files in proshore/entrust-lumen
Package entrust-lumen
Short Description This package provides a flexible way to add Role-based Permissions to Lumen
License MIT
Informations about the package entrust-lumen
Forked from https://github.com/Zizaco/entrust.
ENTRUST (Lumen 5 Package)
Entrust-Lumen is a Fork project modified to run with Lumen. It is a succinct and flexible way to add Role-based Permissions to Lumen 5.
Contents
- Installation
- Configuration
- User relation to roles
- Models
- Role
- Permission
- User
- Soft Deleting
- Usage
- Concepts
- Checking for Roles & Permissions
- User ability
- Blade templates
- Middleware
- Short syntax route filter
- Route filter
- Concepts
- Troubleshooting
- License
- Contribution guidelines
- Additional information
Installation
1) In order to install Lumen 5 Entrust, just add the following to your composer.json. Then run composer update
:
to your composer.json. Then run composer install
or composer update
.
Then in your bootstrap/app.php
add
in the same file find the line with
and add the facades as
.
If you are going to use Middleware (requires Lumen 5.1 or later) you also need to add
to $app->routeMiddleware
methods array in bootstrap/app.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.
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 entrust.php
file will be created in your app/config directory.
Note: You may need to install lumen-vendor-publish to publish the entrust.php
file.
So that your custom configurations be integrated in your app, insert this line in your bootstrap/app.php
User relation to roles
Now generate the Entrust migration:
It will generate the <timestamp>_entrust_setup_tables.php
migration.
You may now run it with the artisan migrate command:
After the migration, four new tables will be present:
roles
— stores role recordspermissions
— stores permission recordsrole_user
— stores many-to-many relations between roles and userspermission_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:
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:
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:
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
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 creating the following Role
s and Permission
s:
Next, with both roles created let's assign them to the users.
Thanks to the HasRole
trait this is as easy as:
Now we just need to add permissions to those Roles:
Checking for Roles & Permissions
Now we can check for roles and permissions simply by doing:
Both hasRole()
and can()
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 Role
s 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-post
permission.
The third parameter is an options array:
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:
The Entrust
class has a shortcut to ability()
for the currently logged in user:
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
For more complex situations use ability
middleware which accepts 3 parameters: roles, permissions, validate_all
Short syntax route filter
To filter a route by permission or role you can call the following in your app/Http/routes.php
:
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:
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.
Route filter
Entrust roles/permissions can be used in filters by simply using the can
and hasRole
methods from within the Facade:
Using a filter to check for a 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:
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 app/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
.
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.
All versions of entrust-lumen with dependencies
illuminate/console Version ~5.0
illuminate/support Version ~5.0
illuminate/cache Version ~5.0