Download the PHP package willypuzzle/laravel-permission without Composer
On this page you can find all versions of the php package willypuzzle/laravel-permission. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package laravel-permission
Associate users with permissions and roles
This package allows you to manage user permissions and roles in a database. This is a modified version of spatie/laravel-permission
Once installed you can do stuff like this:
If you're using multiple guards we've got you covered as well. Every guard will have its own set of permissions and roles that can be assigned to the guard's users. Read about it in the using multiple guards section of the readme.
Because all permissions will be registered on Laravel's gate, you can test if a user has a permission with Laravel's default can
function:
To remember that for permission associated to role or user section is always mandatory.
Installation
This package can be used in Laravel 5.4 or higher.
You can install the package via composer:
In Laravel 5.5 the service provider will automatically get registered. In older versions of the framework just add the service provider in config/app.php
file:
You can publish the migration with:
After the migration has been published you can create the role- and permission-tables by running the migrations:
You can publish the config file with:
When published, the config/permission.php
config file contains:
Usage
First, add the Idsign\Permission\Traits\HasRoles
trait to your User
model(s):
- note that if you need to use
HasRoles
trait with another model ex.Page
you will also need to addprotected $guard_name = 'web';
as well to that model or you would get an error
This package allows for users to be associated with permissions and roles but by sections. Every role is associated with multiple sections and every section for that role is associated with permissions.
A Role
, Section
and a Permission
are regular Eloquent models. They require a name
and can be created like this:
If you're using multiple guards the guard_name
attribute needs to be set as well. Read about it in the using multiple guards section of the readme.
The HasRoles
trait adds Eloquent relationships to your models, which can be accessed directly or used as a base query:
The HasRoles
trait also adds a role
scope to your models to scope the query to certain roles:
The role
scope can accept a string, a \Idsign\Permission\Models\Role
object or an \Illuminate\Support\Collection
object.
Using "direct" permissions (see below to use both roles and permissions)
A permission can be given to any user:
A permission can be revoked from a user:
Or revoke & add new permissions in one go:
You can test if a user has a permission:
...or if a user has multiple permissions:
Saved permissions will be registered with the Illuminate\Auth\Access\Gate
class for the default guard. So you can
test if a user has a permission with Laravel's default can
function:
Using permissions via roles
A role can be assigned to any user:
A role can be removed from a user:
Roles can also be synced:
You can determine if a user has a certain role:
You can also determine if a user has any of a given list of roles:
You can also determine if a user has all of a given list of roles:
The assignRole
, hasRole
, hasAnyRole
, hasAllRoles
and removeRole
functions can accept a
string, a \Idsign\Permission\Models\Role
object or an \Illuminate\Support\Collection
object.
A permission can be given to a role:
You can determine if a role has a certain permission:
A permission can be revoked from a role:
The givePermissionTo
and revokePermissionTo
functions can accept a
string or a Idsign\Permission\Models\Permission
object and a string or a Idsign\Permission\Models\Section
as section.
Permissions are inherited from roles automatically. Additionally, individual permissions can be assigned to the user too. For instance:
In the above example, a role is given permission to edit articles and this role is assigned to a user.
Now the user can edit articles and additionally delete articles. The permission of 'delete articles' is the user's direct permission because it is assigned directly to them.
When we call $user->hasDirectPermission('delete articles', 'blog')
it returns true
,
but false
for $user->hasDirectPermission('edit articles', 'blog')
.
This method is useful if one builds a form for setting permissions for roles and users in an application and wants to restrict or change inherited permissions of roles of the user, i.e. allowing to change only direct permissions of the user.
You can list all of these permissions:
All these responses are collections of Idsign\Permission\Models\Permission
objects.
If we follow the previous example, the first response will be a collection with the delete article
permission and
the second will be a collection with the edit article
permission and the third will contain both.
Get Permissions' tree of a user
It could be useful to get the permission tree (permission divided by sections) of a certain user. In order to do this you can use the method $user->getPermissionsTree() of HasRole trait.
Using Blade directives
This package also adds Blade directives to verify whether the currently logged in user has all or any of a given list of roles.
Optionally you can pass in the guard
that the check will be performed on as a second argument.
Blade and Roles
Test for a specific role:
is the same as
Test for any role in a list:
Test for all roles:
Blade and Permissions
This package doesn't add any permission-specific Blade directives. Instead, use Laravel's native @can
directive to check if a user has a certain permission.
or
Using multiple guards
When using the default Laravel auth configuration all of the above methods will work out of the box, no extra configuration required.
However, when using multiple guards they will act like namespaces for your permissions and roles. Meaning every guard has its own set of permissions and roles that can be assigned to their user model.
Using permissions and roles with multiple guards
By default the default guard (config('auth.defaults.guard')
) will be used as the guard for new permissions and roles. When creating permissions and roles for specific guards you'll have to specify their guard_name
on the model:
To check if a user has permission for a specific guard:
Assigning permissions and roles to guard users
You can use the same methods to assign permissions and roles to users as described above in using permissions via roles. Just make sure the guard_name
on the permission or role matches the guard of the user, otherwise a GuardDoesNotMatch
exception will be thrown.
Using blade directives with multiple guards
You can use all of the blade directives listed in using blade directives by passing in the guard you wish to use as the second argument to the directive:
Using a middleware
This package comes with RoleMiddleware
and PermissionMiddleware
middleware. You can add them inside your app/Http/Kernel.php
file.
Then you can protect your routes using middleware rules:
Alternatively, you can separate multiple roles or permission with a |
(pipe) character:
You can protect your controllers similarly, by setting desired middleware in the constructor:
You can protect crud routes with \Idsign\Permission\Middlewares\CrudMiddleware, see config file for more informations.
Catching role and permission failures
If you want to override the default 403
response, you can catch the UnauthorizedException
using your app's exception handler:
State Management
User
You can set parameters for user state manage (see config for more information). You can call isEnabled method (of HasRole trait) to check if a user is enabled. If a User is disabled it couldn't be allowed to enter in any section for any role or permission.
State management is even for roles and permission, you have to set the state field in the database, use constant in Role and Permission contracts to retrieve the value.
When state is disabled in permission any request will be not allowed in that permission for every user that is linked at that permission. When state is disable in role any request on permission linked to that role will be not allowed. The same is for the sections.
Using artisan commands
You can create a role or permission from a console with artisan commands.
When creating permissions and roles for specific guards you can specify the guard names as a second argument:
Unit Testing
In your application's tests, if you are not seeding roles and permissions as part of your test setUp()
then you may run into a chicken/egg situation where roles and permissions aren't registered with the gate (because your tests create them after that gate registration is done). Working around this is simple: In your tests simply add a setUp()
instruction to re-register the permissions, like this:
Database Seeding
Two notes about Database Seeding:
-
It is best to flush the
idsign.permission.cache.permissions
andidsign.permission.cache.sections
before seeding, to avoid cache conflict errors. This can be done from an Artisan command (see Troubleshooting: Cache section, later) or directly in a seeder class (see example below). - Here's a sample seeder, which clears the cache, creates permissions and then assigns permissions to roles:
Extending
If you need to extend or replace the existing Role
or Permission
models you just need to
keep the following things in mind:
- Your
Role
model needs to implement theIdsign\Permission\Contracts\Role
contract - Your
Permission
model needs to implement theIdsign\Permission\Contracts\Permission
contract - Your
Section
model needs to implement theIdsign\Permission\Contracts\Section
contract -
You can publish the configuration with this command:
And update the
models.role
,models.permission
andmodels.section
values
Cache
Role and Permission data are cached to speed up performance.
When you use the supplied methods for manipulating roles and permissions, the cache is automatically reset for you:
HOWEVER, if you manipulate permission/role data directly in the database instead of calling the supplied methods, then you will not see the changes reflected in the application unless you manually reset the cache.
Manual cache reset
To manually reset the cache for this package, run:
Cache Identifier
TIP: If you are leveraging a caching service such as redis
or memcached
and there are other sites
running on your server, you could run into cache clashes. It is prudent to set your own cache prefix
in /config/cache.php
to something unique for each application. This will prevent other applications
from accidentally using/changing your cached data.
Testing
Changelog
Please see CHANGELOG for more information what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security
If you discover any security-related issues, please email [email protected] instead of using the issue tracker.
Credits
- Freek Van der Herten(Original developer)
- Domenico Rizzo(who made the section extension)
- All Contributors
License
The MIT License (MIT). Please see License File for more information.