This package allows to save permissions and roles in a database. It is built upon Laravel's authorization functionality that was introduced in version 5.1.11
Once installed you can do stuff like this:
//adding permissions to a user
$user->givePermissionTo('edit articles');
//adding permissions via a role
$user->assignRole('writer');
$user2->assignRole('writer');
$role->givePermissionTo('edit articles');You can test if a user has a permission with Laravel's default can-function.
$user->can('edit articles');If you want a drop-in middleware to check permissions, check out our authorize package: https://github.com/spatie/laravel-authorize
Spatie is webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
You can install the package via composer:
$ composer require spatie/laravel-permissionThis service provider must be installed.
// config/app.php
'providers' => [
...
Spatie\Permission\PermissionServiceProvider::class,
];You can publish the migration with:
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="migrations"The package assumes that your users table name is called "users". If this is not the case you should manually edit the published migration to use your custom table name.
After the migration has been published you can create the role- and permission-tables by running the migrations:
php artisan migrateYou can publish the config-file with:
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="config"This is the contents of the published config file:
return [
/*
|--------------------------------------------------------------------------
| Authorization Models
|--------------------------------------------------------------------------
*/
'models' => [
/*
|--------------------------------------------------------------------------
| Permission Model
|--------------------------------------------------------------------------
|
| When using the "HasRoles" trait from this package, we need to know which
| Eloquent model should be used to retrieve your permissions. Of course, it
| is often just the "Permission" model but you may use whatever you like.
|
| The model you want to use as a Permission model needs to implement the
| `Spatie\Permission\Contracts\Permission` contract.
|
*/
'permission' => Spatie\Permission\Models\Permission::class,
/*
|--------------------------------------------------------------------------
| Role Model
|--------------------------------------------------------------------------
|
| When using the "HasRoles" trait from this package, we need to know which
| Eloquent model should be used to retrieve your roles. Of course, it
| is often just the "Role" model but you may use whatever you like.
|
| The model you want to use as a Role model needs to implement the
| `Spatie\Permission\Contracts\Role` contract.
|
*/
'role' => Spatie\Permission\Models\Role::class,
],
/*
|--------------------------------------------------------------------------
| Authorization Tables
|--------------------------------------------------------------------------
*/
'table_names' => [
/*
|--------------------------------------------------------------------------
| Roles Table
|--------------------------------------------------------------------------
|
| When using the "HasRoles" trait from this package, we need to know which
| table should be used to retrieve your roles. We have chosen a basic
| default value but you may easily change it to any table you like.
|
*/
'roles' => 'roles',
/*
|--------------------------------------------------------------------------
| Permissions Table
|--------------------------------------------------------------------------
|
| When using the "HasRoles" trait from this package, we need to know which
| table should be used to retrieve your permissions. We have chosen a basic
| default value but you may easily change it to any table you like.
|
*/
'permissions' => 'permissions',
/*
|--------------------------------------------------------------------------
| User Permissions Table
|--------------------------------------------------------------------------
|
| When using the "HasRoles" trait from this package, we need to know which
| table should be used to retrieve your users permissions. We have chosen a
| basic default value but you may easily change it to any table you like.
|
*/
'user_has_permissions' => 'user_has_permissions',
/*
|--------------------------------------------------------------------------
| User Roles Table
|--------------------------------------------------------------------------
|
| When using the "HasRoles" trait from this package, we need to know which
| table should be used to retrieve your users roles. We have chosen a
| basic default value but you may easily change it to any table you like.
|
*/
'user_has_roles' => 'user_has_roles',
/*
|--------------------------------------------------------------------------
| Role Permissions Table
|--------------------------------------------------------------------------
|
| When using the "HasRoles" trait from this package, we need to know which
| table should be used to retrieve your roles permissions. We have chosen a
| basic default value but you may easily change it to any table you like.
|
*/
'role_has_permissions' => 'role_has_permissions',
],
];First add the Spatie\Permission\Traits\HasRoles-trait to your User model.
use Illuminate\Foundation\Auth\User as Authenticatable;
use Spatie\Permission\Traits\HasRoles;
class User extends Authenticatable
{
use HasRoles;
// ...
}This package allows for users to be associated with roles. Permissions can be associated with roles.
A Role and a Permission are regular Eloquent-models. They can have a name and can be created like this:
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;
$role = Role::create(['name' => 'writer']);
$permission = Permission::create(['name' => 'edit articles']);The HasRoles adds eloquent relationships to your models, which can be accessed directly or used as a base query.
$permissions = $user->permissions;
$roles = $user->roles()->pluck('name');###Using permissions A permission can be given to a user:
$user->givePermissionTo('edit articles');A permission can be revoked from a user:
$user->revokePermissionTo('edit articles');You can test if a user has a permission:
$user->hasPermissionTo('edit articles');Saved permissions will be registered with the Illuminate\Auth\Access\Gate-class. So you can
test if a user has a permission with Laravel's default can-function.
$user->can('edit articles');###Using roles and permissions A role can be assigned to a user:
$user->assignRole('writer');A role can be removed from a user:
$user->removeRole('writer');You can determine if a user has a certain role:
$user->hasRole('writer');You can also determine if a user has any of a given list of roles:
$user->hasAnyRole(Role::all());You can also determine if a user has all of a given list of roles:
$user->hasAllRoles(Role::all());The assignRole, hasRole, hasAnyRole, hasAllRoles and removeRole-functions can accept a
string, a Spatie\Permission\Models\Role-object or an \Illuminate\Support\Collection-object.
A permission can be given to a role:
$role->givePermissionTo('edit articles');A permission can be revoked from a role:
$role->revokePermissionTo('edit articles');The givePermissionTo and revokePermissionTo-functions can accept a
string or a Spatie\Permission\Models\Permission-object.
Saved permission and roles are also registered with the Illuminate\Auth\Access\Gate-class.
$user->can('edit articles');###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.
@role('writer')
I'm a writer!
@else
I'm not a writer...
@endrole@hasrole('writer')
I'm a writer!
@else
I'm not a writer...
@endhasrole@hasanyrole(Role::all())
I have one or more of these roles!
@else
I have none of these roles...
@endhasanyrole@hasallroles(Role::all())
I have all of these roles!
@else
I don't have all of these roles...
@endhasallrolesYou can use Laravel's native @can directive to check if a user has a certain permission.
If you need to extend or replace the existing Role or Permission models you just need to
keep the following things in mind:
- Your
Rolemodel needs to implement theSpatie\Permission\Contracts\Rolecontract - Your
Permissionmodel needs to implement theSpatie\Permission\Contracts\Permissioncontract - You must publish the configuration with this command:
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider" --tag="config"and update themodels.roleandmodels.permissionvalues
Please see CHANGELOG for more information what has changed recently.
$ composer testPlease see CONTRIBUTING for details.
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
This package is heavily based on Jeffrey Way's awesome Laracasts-lesson on roles and permissions. His original code can be found in this repo on GitHub.
Spatie is webdesign agency in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.
The MIT License (MIT). Please see License File for more information.