Laravel Permission

https://spatie.be/docs/laravel-permission/v6
Admin
Laravel Permission is a package that allows you to easily add and manage user permissions and roles...
Tokens:18,336
Snippets:293
Trust Score:9.9
Update:3 months ago
Show doc for...
Tokens:
Raw
### Initialize Laravel Project and Install Package

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/new-app

Commands to create a new Laravel project, configure SQLite, install the permission package, and apply the HasRoles trait to the User model.

```bash
cd ~/Sites
laravel new mypermissionsdemo
# (No Starter Kit is needed, but you could go with Livewire or Breeze/Jetstream, with Laravel's Built-In-Auth; or use Bootstrap using laravel/ui described later, below)
# (You might be asked to select a dark-mode-support choice)
# (Choose your desired testing framework: Pest or PHPUnit)
# (If offered, say Yes to initialize a Git repo, so that you can track your code changes)
# (If offered a database selection, choose SQLite, because it is simplest for test scenarios)
# (If prompted, say Yes to run default database migrations)
# (If prompted, say Yes to run npm install and related commands)

cd mypermissionsdemo

# The following git commands are not needed if you Initialized a git repo while "laravel new" was running above:
git init
git add .
git commit -m "Fresh Laravel Install"

# These Environment steps are not needed if you already selected SQLite while "laravel new" was running above:
cp -n .env.example .env
sed -i '' 's/DB_CONNECTION=mysql/DB_CONNECTION=sqlite/' .env
sed -i '' 's/DB_DATABASE=/#DB_DATABASE=/' .env
touch database/database.sqlite

# Package
composer require spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
git add .
git commit -m "Add Spatie Laravel Permissions package"
php artisan migrate:fresh

# Add `HasRoles` trait to User model
sed -i '' $'s/use HasFactory, Notifiable;/use HasFactory, Notifiable;\\n    use \\Spatie\\Permission\\Traits\\HasRoles;/' app/Models/User.php
sed -i '' $'s/use HasApiTokens, HasFactory, Notifiable;/use HasApiTokens, HasFactory, Notifiable;\\n    use \\Spatie\\Permission\\Traits\\HasRoles;/' app/Models/User.php
git add . && git commit -m "Add HasRoles trait"
```

--------------------------------

### Check installed package version

Source: https://spatie.be/docs/laravel-permission/v6/about-us

Use this command to verify the currently installed version of the spatie/laravel-permission package in your project.

```bash
composer show spatie/laravel-permission
```

--------------------------------

### Assign Super-Admin Role on Team Creation

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/teams-permissions

Example of using a model boot method to assign a global role to a user when a new team is created.

```php
namespace App\Models;

class YourTeamModel extends \Illuminate\Database\Eloquent\Model
{
    // ...
    public static function boot()
    {
        parent::boot();

        // here assign this team to a global user with global default role
        self::created(function ($model) {
           // temporary: get session team_id for restore at end
           $session_team_id = getPermissionsTeamId();
           // set actual new team_id to package instance
           setPermissionsTeamId($model);
           // get the admin user and assign roles/permissions on new team model
           User::find('your_user_id')->assignRole('Super Admin');
           // restore session team_id to package instance using temporary value stored above
           setPermissionsTeamId($session_team_id);
        });
    }
    // ...
```

--------------------------------

### Install package via Composer

Source: https://spatie.be/docs/laravel-permission/v6/installation-lumen

Use Composer to add the package to your project dependencies.

```bash
composer require spatie/laravel-permission
```

--------------------------------

### Enable Events in Configuration

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/events

Set the events_enabled key to true in the config/permission.php file to start firing events.

```php
events_enabled => true
```

--------------------------------

### Clear Cache in Test setUp

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/testing

Re-register permissions by clearing the cache within the test class setUp method to ensure roles and permissions are correctly registered with the gate.

```php
    protected function setUp(): void
    {
        // first include all the normal setUp operations
        parent::setUp();

        // now de-register all the roles and permissions by clearing the permission cache
        $this->app->make(\Spatie\Permission\PermissionRegistrar::class)->forgetCachedPermissions();
    }
```

--------------------------------

### Install package via Composer

Source: https://spatie.be/docs/laravel-permission/v6/installation-laravel

Use this command to add the package to your Laravel project dependencies.

```bash
 composer require spatie/laravel-permission
```

--------------------------------

### Roles and Permissions Seeder Class

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/seeding

A complete example of a seeder class that clears cache, defines permissions, and assigns them to roles.

```php
use Illuminate\Database\Seeder;
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

class RolesAndPermissionsSeeder extends Seeder
{
    public function run(): void
    {
        // Reset cached roles and permissions
        app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();

        // create permissions
        Permission::create(['name' => 'edit articles']);
        Permission::create(['name' => 'delete articles']);
        Permission::create(['name' => 'publish articles']);
        Permission::create(['name' => 'unpublish articles']);

        // update cache to know about the newly created permissions (required if using WithoutModelEvents in seeders)
        app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();

        // create roles and assign created permissions

        // this can be done as separate statements
        $role = Role::create(['name' => 'writer']);
        $role->givePermissionTo('edit articles');

        // or may be done by chaining
        $role = Role::create(['name' => 'moderator'])
            ->givePermissionTo(['publish articles', 'unpublish articles']);

        $role = Role::create(['name' => 'super-admin']);
        $role->givePermissionTo(Permission::all());
    }
}
```

--------------------------------

### Register service providers and configuration

Source: https://spatie.be/docs/laravel-permission/v6/installation-lumen

Configure the package and register the necessary service providers in bootstrap/app.php.

```php
$app->configure('permission');
$app->alias('cache', \Illuminate\Cache\CacheManager::class);  // if you don't have this already
$app->register(Spatie\Permission\PermissionServiceProvider::class);
```

--------------------------------

### Copy configuration and migration files

Source: https://spatie.be/docs/laravel-permission/v6/installation-lumen

Manually copy the package configuration and migration files into your project structure.

```bash
mkdir -p config
cp vendor/spatie/laravel-permission/config/permission.php config/permission.php
cp vendor/spatie/laravel-permission/database/migrations/create_permission_tables.php.stub database/migrations/2018_01_01_000000_create_permission_tables.php
```

--------------------------------

### Run migrations

Source: https://spatie.be/docs/laravel-permission/v6/installation-laravel

Executes the migrations to create the necessary database tables for the package.

```bash
 php artisan migrate
```

--------------------------------

### Configure Super Admin in Policy before()

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/super-admin

Implement the before() method within individual Policy classes to grant super-admin control on a per-policy basis.

```php
use App\Models\User; // could be any Authorizable model

/**
 * Perform pre-authorization checks on the model.
 */
public function before(User $user, string $ability): ?bool
{
    if ($user->hasRole('Super Admin')) {
        return true;
    }

    return null; // see the note above in Gate::before about why null must be returned here.
}
```

--------------------------------

### Create Roles with Team IDs

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/teams-permissions

Demonstrates creating global roles, team-specific roles, and roles using the default global team ID.

```php
// with null team_id it creates a global role; global roles can be assigned to any team and they are unique
Role::create(['name' => 'writer', 'team_id' => null]);

// creates a role with team_id = 1; team roles can have the same name on different teams
Role::create(['name' => 'reader', 'team_id' => 1]);

// creating a role without team_id makes the role take the default global team_id
Role::create(['name' => 'reviewer']);
```

--------------------------------

### Publish configuration and migrations

Source: https://spatie.be/docs/laravel-permission/v6/installation-laravel

Publishes the package's migration files and the configuration file to your application.

```bash
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
```

--------------------------------

### Package Methods Supporting BackedEnums

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/enums

List of common package methods that accept BackedEnum instances directly.

```php
	$user->assignRole(RolesEnum::WRITER);
	$user->removeRole(RolesEnum::EDITOR);

    $role->givePermissionTo(PermissionsEnum::EDITPOSTS);
    $role->revokePermissionTo(PermissionsEnum::EDITPOSTS);

    $user->givePermissionTo(PermissionsEnum::EDITPOSTS);
    $user->revokePermissionTo(PermissionsEnum::EDITPOSTS);

	$user->hasPermissionTo(PermissionsEnum::EDITPOSTS);
	$user->hasAnyPermission([PermissionsEnum::EDITPOSTS, PermissionsEnum::VIEWPOSTS]);
	$user->hasDirectPermission(PermissionsEnum::EDITPOSTS);

    $user->hasRole(RolesEnum::WRITER);
    $user->hasAllRoles([RolesEnum::WRITER, RolesEnum::EDITOR]);
    $user->hasExactRoles([RolesEnum::WRITER, RolesEnum::EDITOR, RolesEnum::MANAGER]);
```

--------------------------------

### Create Permission Performance Optimization

Source: https://spatie.be/docs/laravel-permission/v6/best-practices/performance

Use make and saveOrFail for faster permission creation on large databases compared to the standard create method.

```php
Permission::create([attributes]);
```

```php
$permission = Permission::make([attributes]); 
$permission->saveOrFail();
```

--------------------------------

### Configure Super Admin with Gate::after

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/super-admin

Use Gate::after to perform Super Admin checks, useful when specific restrictions should still apply to the Super Admin.

```php
// somewhere in a service provider

Gate::after(function ($user, $ability) {
   return $user->hasRole('Super Admin'); // note this returns boolean
});
```

--------------------------------

### Copy auth configuration

Source: https://spatie.be/docs/laravel-permission/v6/installation-lumen

Copy the auth configuration file from the vendor directory if it does not exist.

```bash
cp vendor/laravel/lumen-framework/config/auth.php config/auth.php
```

--------------------------------

### Create Roles and Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/basic-usage

Instantiate new roles and permissions using standard Eloquent create methods.

```php
use Spatie\Permission\Models\Role;
use Spatie\Permission\Models\Permission;

$role = Role::create(['name' => 'writer']);
$permission = Permission::create(['name' => 'edit articles']);
```

--------------------------------

### Bulk Insert Permissions and Roles using DB Facade

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/seeding

Demonstrates direct database insertion for permissions and role associations. Note that this approach hard-codes table names and bypasses cache-control features, requiring a manual cache flush.

```php
$permissionsByRole = [
    'admin' => ['restore posts', 'force delete posts'],
    'editor' => ['create a post', 'update a post', 'delete a post'],
    'viewer' => ['view all posts', 'view a post']
];

$insertPermissions = fn ($role) => collect($permissionsByRole[$role])
    ->map(fn ($name) => DB::table('permissions')->insertGetId(['name' => $name, 'guard_name' => 'web']))
    ->toArray();

$permissionIdsByRole = [
    'admin' => $insertPermissions('admin'),
    'editor' => $insertPermissions('editor'),
    'viewer' => $insertPermissions('viewer')
];

foreach ($permissionIdsByRole as $role => $permissionIds) {
    $role = Role::whereName($role)->first();

    DB::table('role_has_permissions')
        ->insert(
            collect($permissionIds)->map(fn ($id) => [
                'role_id' => $role->id,
                'permission_id' => $id
            ])->toArray()
        );
}

// and also add the command to flush the cache again now after doing all these inserts
```

--------------------------------

### Create Roles and Permissions via Artisan

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/artisan

Commands to create roles and permissions, optionally specifying a guard name.

```bash
php artisan permission:create-role writer
```

```bash
php artisan permission:create-permission "edit articles"
```

```bash
php artisan permission:create-role writer web
```

```bash
php artisan permission:create-permission "edit articles" web
```

--------------------------------

### Display Roles and Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/artisan

Command to output a table of all roles and permissions grouped by guard.

```bash
php artisan permission:show
```

--------------------------------

### Configure permission settings for Passport

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/passport

Enable Passport client credentials support in the package configuration file.

```php
// config/permission.php
'use_passport_client_credentials' => true,
```

--------------------------------

### Create Roles with Permissions and Teams

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/artisan

Advanced role creation including linking permissions and setting team IDs.

```bash
php artisan permission:create-role writer web "create articles|edit articles"
```

```bash
php artisan permission:create-role --team-id=1 writer
```

```bash
php artisan permission:create-role writer api --team-id=1
```

--------------------------------

### Enable Wildcard Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/wildcard-permissions

Set the configuration flag in the permission config file to enable wildcard support.

```php
// config/permission.php
'enable_wildcard_permission' => true,
```

--------------------------------

### Configure Super Admin with Gate::before

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/super-admin

Use this in a ServiceProvider to implicitly grant all permissions to the Super Admin role for Gate-related checks.

```php
use Illuminate\Support\Facades\Gate;
// ...
public function boot()
{
    // Implicitly grant "Super Admin" role all permissions
    // This works in the app by using gate-related functions like auth()->user->can() and @can()
    Gate::before(function ($user, $ability) {
        return $user->hasRole('Super Admin') ? true : null;
    });
}
```

--------------------------------

### Define migration schema for custom fields

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/extending

Implement the up method to add nullable string columns to the permissions and roles tables.

```php
public function up()
{
    Schema::table('permissions', function (Blueprint $table) {
        $table->string('description')->nullable();
    });
    Schema::table('roles', function (Blueprint $table) {
        $table->string('description')->nullable();
    });
}
```

--------------------------------

### Generate Role and Permission models

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/uuid

Run these artisan commands to create the model files before adding the HasUuids trait.

```bash
php artisan make:model Role
php artisan make:model Permission
```

--------------------------------

### Add Laravel UI Authentication Scaffolding

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/new-app

Commands to add basic authentication scaffolding using Laravel UI for testing login and permission functionality.

```bash
composer require laravel/ui --dev
php artisan ui bootstrap --auth
# npm install && npm run build
git add . && git commit -m "Setup auth scaffold"
```

--------------------------------

### Create Guard-Specific Roles and Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/multiple-guards

Define roles and permissions explicitly for specific guards to ensure they are scoped correctly.

```php
// Create a manager role for users authenticating with the admin guard:
$role = Role::create(['guard_name' => 'admin', 'name' => 'manager']);

// Define a `publish articles` permission for the admin users belonging to the admin guard
$permission = Permission::create(['guard_name' => 'admin', 'name' => 'publish articles']);

// Define a *different* `publish articles` permission for the regular users belonging to the web guard
$permission = Permission::create(['guard_name' => 'web', 'name' => 'publish articles']);
```

--------------------------------

### Implement Team Middleware

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/teams-permissions

Create a middleware to set the global team ID for the current request context.

```php
namespace App\Http\Middleware;

class TeamsPermission
{

    public function handle($request, \Closure $next){
        if(!empty(auth()->user())){
            // session value set on login
            setPermissionsTeamId(session('team_id'));
        }
        // other custom ways to get team_id
        /*if(!empty(auth('api')->user())){
            // `getTeamIdFromToken()` example of custom method for getting the set team_id 
            setPermissionsTeamId(auth('api')->user()->getTeamIdFromToken());
        }*/

        return $next($request);
    }
}
```

--------------------------------

### Checking Direct Permissions with Package Methods

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/direct-permissions

Methods to check for specific permissions, including support for permission IDs.

```php
$user->hasPermissionTo('edit articles');
```

```php
$user->hasPermissionTo('1');
$user->hasPermissionTo(Permission::find(1)->id);
$user->hasPermissionTo($somePermission->id);
```

--------------------------------

### Enable Teams Permissions Configuration

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/teams-permissions

Set the teams configuration option in the permission config file to enable the feature.

```php
// config/permission.php
'teams' => true,
```

```php
// config/permission.php
'team_foreign_key' => 'custom_team_id',
```

--------------------------------

### Register middleware in bootstrap/app.php

Source: https://spatie.be/docs/laravel-permission/v6/installation-lumen

Define the route middleware for authentication, permissions, and roles.

```php
$app->routeMiddleware([
    'auth'       => App\Http\Middleware\Authenticate::class,
    'permission' => App\Http\Middleware\PermissionMiddleware::class, // cloned from Spatie\Permission\Middleware
    'role'       => App\Http\Middleware\RoleMiddleware::class,  // cloned from Spatie\Permission\Middleware
]);
```

--------------------------------

### Apply Middleware via Static Methods in Routes

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/middleware

Use the static using method to apply middleware to route groups, accepting arrays or pipe-separated strings.

```php
Route::group(['middleware' => [\Spatie\Permission\Middleware\RoleMiddleware::using('manager')]], function () { ... });
Route::group(['middleware' => [\Spatie\Permission\Middleware\PermissionMiddleware::using('publish articles|edit articles')]], function () { ... });
Route::group(['middleware' => [\Spatie\Permission\Middleware\RoleOrPermissionMiddleware::using(['manager', 'edit articles'])]], function () { ... });
```

--------------------------------

### Configure Model Morph Key in permission.php

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/uuid

Update the configuration file to use model_uuid instead of the default model_id.

```php
        'column_names' => [    
        /*
         * Change this if you want to name the related pivots other than defaults
         */
        'role_pivot_key' => null, //default 'role_id',
        'permission_pivot_key' => null, //default 'permission_id',

        /*
         * Change this if you want to name the related model primary key other than
         * `model_id`.
         *
         * For example, this would be nice if your primary keys are all UUIDs. In
         * that case, name this `model_uuid`.
         */
-             'model_morph_key' => 'model_id',
+             'model_morph_key' => 'model_uuid',
        ],
```

--------------------------------

### Configure User Model for Multiple Guards

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/multiple-guards

Define allowed guards in the User model using either a property or a method to support multiple authentication contexts.

```php
    protected $guard_name = ['web', 'admin'];
```

```php
    public function guardName() { return ['web', 'admin']; }
```

--------------------------------

### Create migration for custom fields

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/extending

Use Artisan to generate a migration file for adding new columns to existing tables.

```bash
php artisan make:migration add_description_to_permissions_tables
```

--------------------------------

### Register the custom Client model

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/passport

Instruct Passport to use your extended Client model by adding this call to the boot method of your AuthServiceProvider.

```php
Passport::useClientModel(\App\Models\Client::class); // Use the namespace of your extended Client.
```

--------------------------------

### Sync Permissions and Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/basic-usage

Synchronize a set of permissions to a role or roles to a permission, replacing existing associations.

```php
$role->syncPermissions($permissions);
$permission->syncRoles($roles);
```

--------------------------------

### Configure Middleware Priority

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/teams-permissions

Register the custom team middleware in the application service provider to ensure it runs before binding substitution.

```php
use App\Http\Middleware\YourCustomMiddlewareClass;
use Illuminate\Foundation\Http\Kernel;
use Illuminate\Routing\Middleware\SubstituteBindings;
use Illuminate\Support\ServiceProvider;

class AppServiceProvider extends ServiceProvider
{
    public function register(): void
    {
        //
    }

    public function boot(): void
    {
        /** @var Kernel $kernel */
        $kernel = app()->make(Kernel::class);

        $kernel->addToMiddlewarePriorityBefore(
            YourCustomMiddlewareClass::class,
            SubstituteBindings::class,
        );
    }
}
```

--------------------------------

### Retrieve Users and Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/basic-usage

Common Eloquent queries for fetching users with their associated roles or permissions, and filtering roles.

```php
$allUsersWithAllTheirRoles = User::with('roles')->get();
$allUsersWithAllTheirDirectPermissions = User::with('permissions')->get();
$allRolesInDatabase = Role::all()->pluck('name');
$usersWithoutAnyRoles = User::doesntHave('roles')->get();
$allRolesExceptAandB = Role::whereNotIn('name', ['role A', 'role B'])->get();
```

--------------------------------

### Assigning Roles to Users

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Assign single or multiple roles to a user instance.

```php
$user->assignRole('writer');

// You can also assign multiple roles at once
$user->assignRole('writer', 'admin');
// or as an array
$user->assignRole(['writer', 'admin']);
```

--------------------------------

### Syncing User Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Replace all current user roles with a new set.

```php
// All current roles will be removed from the user and replaced by the array given
$user->syncRoles(['writer', 'admin']);
```

--------------------------------

### User Seeding without Factory States

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/seeding

Assigns roles to a batch of users after creation using the each method.

```php
// Seeder:
User::factory()
    ->count(50)
    ->create()
    ->each(function ($user) {
        $user->assignRole('Member');
    });
```

--------------------------------

### Bulk Insert Permissions using Eloquent

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/seeding

Uses the Permission model to insert multiple permissions at once.

```php
    $arrayOfPermissionNames = ['writer', 'editor'];
    $permissions = collect($arrayOfPermissionNames)->map(function ($permission) {
        return ['name' => $permission, 'guard_name' => 'web'];
    });

    Permission::insert($permissions->toArray());
```

--------------------------------

### Checking Multiple Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/direct-permissions

Methods to verify if a user possesses any or all of a provided list of permissions.

```php
$user->hasAnyPermission(['edit articles', 'publish articles', 'unpublish articles']);
```

```php
$user->hasAllPermissions(['edit articles', 'publish articles', 'unpublish articles']);
```

```php
$user->hasAnyPermission(['edit articles', 1, 5]);
```

--------------------------------

### Managing Role Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Assign, check, revoke, or sync permissions for a role.

```php
$role->givePermissionTo('edit articles');
```

```php
$role->hasPermissionTo('edit articles');
```

```php
$role->revokePermissionTo('edit articles');
```

```php
$role->syncPermissions(['edit articles', 'delete articles']);
```

--------------------------------

### Apply Package Middleware to Routes

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/middleware

Use registered middleware aliases to restrict access to routes based on roles or permissions.

```php
Route::group(['middleware' => ['role:manager']], function () { ... });
Route::group(['middleware' => ['permission:publish articles']], function () { ... });
Route::group(['middleware' => ['role_or_permission:publish articles']], function () { ... });

// for a specific guard:
Route::group(['middleware' => ['role:manager,api']], function () { ... });

// multiple middleware
Route::group(['middleware' => ['role:manager','permission:publish articles']], function () { ... });
```

--------------------------------

### Retrieve User Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Methods to fetch direct, role-based, or all combined permissions for a user instance.

```php
// Direct permissions
$user->getDirectPermissions() // Or $user->permissions;

// Permissions inherited from the user's roles
$user->getPermissionsViaRoles();

// All permissions which apply on the user (inherited and direct)
$user->getAllPermissions();
```

--------------------------------

### Available Permission Events

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/events

List of event classes available since v6.15.0 for monitoring role and permission changes.

```php
\Spatie\Permission\Events\RoleAttached::class
\Spatie\Permission\Events\RoleDetached::class
\Spatie\Permission\Events\PermissionAttached::class
\Spatie\Permission\Events\PermissionDetached::class
```

--------------------------------

### Register AuthServiceProvider

Source: https://spatie.be/docs/laravel-permission/v6/installation-lumen

Uncomment or register the AuthServiceProvider in bootstrap/app.php to enable the authorization layer.

```php
$app->register(App\Providers\AuthServiceProvider::class);
```

--------------------------------

### Assigning Direct Permissions to Users

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/direct-permissions

Methods to grant one or multiple permissions directly to a user instance.

```php
$user->givePermissionTo('edit articles');

// You can also give multiple permission at once
$user->givePermissionTo('edit articles', 'delete articles');

// You may also pass an array
$user->givePermissionTo(['edit articles', 'delete articles']);
```

--------------------------------

### Check Wildcard Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/wildcard-permissions

Verify if a user has access based on assigned wildcard permissions.

```php
// will be true
$user->can('posts.create');
$user->can('posts.edit');
$user->can('posts.delete');
```

--------------------------------

### Checking All User Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Verify if a user has all roles in a given list.

```php
$user->hasAllRoles(Role::all());
```

--------------------------------

### Checking Direct User Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Verify permissions assigned directly to a user.

```php
// Check if the user has Direct permission
$user->hasDirectPermission('edit articles')

// Check if the user has All direct permissions
$user->hasAllDirectPermissions(['edit articles', 'delete articles']);

// Check if the user has Any permission directly
$user->hasAnyDirectPermission(['create articles', 'delete articles']);
```

--------------------------------

### Reset Package Cache

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/artisan

Manually clear the cached roles and permissions.

```bash
php artisan permission:cache-reset
```

--------------------------------

### Checking Exact User Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Verify if a user has exactly the provided set of roles.

```php
$user->hasExactRoles(Role::all());
```

--------------------------------

### Define a Role Enum

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/enums

Create a BackedEnum to manage application roles. The label method provides a way to return human-readable strings.

```php
namespace App\Enums;

enum RolesEnum: string
{
    // case NAMEINAPP = 'name-in-database';

    case WRITER = 'writer';
    case EDITOR = 'editor';
    case USERMANAGER = 'user-manager';

    // extra helper to allow for greater customization of displayed values, without disclosing the name/value data directly
    public function label(): string
    {
        return match ($this) {
            static::WRITER => 'Writers',
            static::EDITOR => 'Editors',
            static::USERMANAGER => 'User Managers',
        };
    }
}
```

--------------------------------

### Assign Wildcard Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/wildcard-permissions

Assigning a wildcard permission allows access to all sub-actions defined by the pattern.

```php
Permission::create(['name'=>'posts.*']);
$user->givePermissionTo('posts.*');
// is the same as
Permission::create(['name'=>'posts']);
$user->givePermissionTo('posts');
```

--------------------------------

### Manual Cache Reset

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/cache

Methods to manually clear the package cache via application code or Artisan command.

```php
app()->make(\Spatie\Permission\PermissionRegistrar::class)->forgetCachedPermissions();
```

```bash
php artisan permission:cache-reset
```

--------------------------------

### Use Subparts in Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/wildcard-permissions

Use commas to define multiple subparts within a permission string for complex schemes.

```php
// user can only do the actions create, update and view on both resources posts and users
Permission::create(['name'=>'posts,users.create,update,view']);
$user->givePermissionTo('posts,users.create,update,view');

// user can do the actions create, update, view on any available resource
Permission::create(['name'=>'*.create,update,view']);
$user->givePermissionTo('*.create,update,view');

// user can do any action on posts with ids 1, 4 and 6 
Permission::create(['name'=>'posts.*.1,4,6']);
$user->givePermissionTo('posts.*.1,4,6');
```

--------------------------------

### Implementing a Custom Gate::before Check

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/custom-permission-check

Define a custom permission check in your AuthServiceProvider or AppServiceProvider. Ensure the custom method (e.g., hasTokenPermission) is implemented on your user model.

```php
use Illuminate	Support	Facades	Gate;

public function boot()
{
    ...

    Gate::before(function ($user, $ability) {
        return $user->hasTokenPermission($ability) ?: null;
    });
}
```

--------------------------------

### Checking Any User Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Determine if a user has any of the provided roles.

```php
$user->hasAnyRole(['writer', 'reader']);
// or
$user->hasAnyRole('writer', 'reader');
```

--------------------------------

### Define Wildcard Permission String

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/wildcard-permissions

Wildcard permissions are represented as dot-separated strings.

```php
$permission = 'posts.create.1';
```

--------------------------------

### Automatic Cache Refresh Methods

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/cache

Built-in methods for roles and permissions that automatically trigger a cache reset.

```php
// When handling permissions assigned to roles:
$role->givePermissionTo('edit articles');
$role->revokePermissionTo('edit articles');
$role->syncPermissions(params);

// When linking roles to permissions:
$permission->assignRole('writer');
$permission->removeRole('writer');
$permission->syncRoles(params);
```

--------------------------------

### Clear configuration cache

Source: https://spatie.be/docs/laravel-permission/v6/installation-laravel

Clears the configuration cache to ensure the package can access its settings during migration.

```bash
 php artisan optimize:clear
 # or
 php artisan config:clear
```

--------------------------------

### Query Roles and Permissions for Other Teams

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/teams-permissions

Required steps to switch the active team ID and clear cached model relations before querying permissions.

```php
// set active global team_id
setPermissionsTeamId($new_team_id);

// $user = Auth::user();

// unset cached model relations so new team relations will get reloaded
$user->unsetRelation('roles')->unsetRelation('permissions');

// Now you can check:
$roles = $user->roles;
$hasRole = $user->hasRole('my_role');
$user->hasPermissionTo('foo');
$user->can('bar');
// etc
```

--------------------------------

### Assign Permissions to Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/basic-usage

Associate permissions with roles using either the role or permission model instance.

```php
$role->givePermissionTo($permission);
$permission->assignRole($role);
```

--------------------------------

### User Seeding with Factory States

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/seeding

Assigns roles to users automatically using Laravel factory states.

```php
// Factory:
    public function definition() {...}

    public function active(): static
    {
        return $this->state(fn (array $attributes) => [
            'status' => 1,
            ])
            ->afterCreating(function (User $user) {
                $user->assignRole('ActiveMember');
            });
    }

// Seeder:
// To create 4 users using this 'active' state in a Seeder:
User::factory(4)->active()->create();
```

--------------------------------

### Assign roles and permissions

Source: https://spatie.be/docs/laravel-permission/v6

Assign permissions directly to users or via roles to manage access control.

```php
// Adding permissions to a user
$user->givePermissionTo('edit articles');

// Adding permissions via a role
$user->assignRole('writer');

$role->givePermissionTo('edit articles');
```

--------------------------------

### Checking User Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Verify if a user possesses specific roles.

```php
$user->hasRole('writer');

// or at least one role from an array of roles:
$user->hasRole(['editor', 'moderator']);
```

--------------------------------

### Retrieve User Permissions and Roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/basic-usage

Access direct permissions, inherited permissions, and role names associated with a user model.

```php
// get a list of all permissions directly assigned to the user
$permissionNames = $user->getPermissionNames(); // collection of name strings
$permissions = $user->permissions; // collection of permission objects

// get all permissions for the user, either directly, or from roles, or from both
$permissions = $user->getDirectPermissions();
$permissions = $user->getPermissionsViaRoles();
$permissions = $user->getAllPermissions();

// get the names of the user's roles
$roles = $user->getRoleNames(); // Returns a collection
```

--------------------------------

### Authorize using Enums

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/enums

Use Enums directly in package methods that support them, or append ->value for compatibility with standard Laravel Gate features.

```php
// the following are identical because `hasPermissionTo` is aware of `BackedEnum` support:
$user->hasPermissionTo(PermissionsEnum::VIEWPOSTS);
$user->hasPermissionTo(PermissionsEnum::VIEWPOSTS->value);

// when calling Gate features, such as Model Policies, etc, prior to Laravel v11.23.0
$user->can(PermissionsEnum::VIEWPOSTS->value);
$model->can(PermissionsEnum::VIEWPOSTS->value);

// Blade directives:
@can(PermissionsEnum::VIEWPOSTS->value)
```

--------------------------------

### Handle UnauthorizedException in Laravel 11

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/exceptions

Use the withExceptions method in the bootstrap/app.php file to register a custom renderer for unauthorized exceptions.

```php

->withExceptions(function (Exceptions $exceptions) {
    $exceptions->render(function (\Spatie\Permission\Exceptions\UnauthorizedException $e, $request) {
        return response()->json([
            'responseMessage' => 'You do not have the required authorization.',
            'responseStatus'  => 403,
        ]);
    });
}
```

--------------------------------

### Create Roles using Enums

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/enums

When creating roles or permissions, pass the Enum value property to Eloquent methods.

```php
  $role = app(Role::class)->findOrCreate(RolesEnum::WRITER->value, 'web');
```

--------------------------------

### Reinitialize PermissionRegistrar Cache

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/cache

Use this to refresh the cache store and configuration when switching tenants or cache stores during a single request lifecycle.

```php
app()->make(\Spatie\Permission\PermissionRegistrar::class)->initializeCache();
```

--------------------------------

### Update Roles and Permissions Migration for UUIDs

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/uuid

Adjust the primary keys and foreign key references in the migration file to support UUIDs.

```php
    Schema::create($tableNames['permissions'], function (Blueprint $table) {
-         $table->bigIncrements('id'); // permission id
+         $table->uuid('uuid')->primary()->unique(); // permission id
//...
    });

    Schema::create($tableNames['roles'], function (Blueprint $table) {
-         $table->bigIncrements('id'); // role id
+         $table->uuid('uuid')->primary()->unique(); // role id
//...
    });

    Schema::create($tableNames['model_has_permissions'], function (Blueprint $table) use ($tableNames, $columnNames) {
-         $table->unsignedBigInteger($pivotPermission);
+         $table->uuid($pivotPermission);
        $table->string('model_type');
//...
        $table->foreign($pivotPermission)
-             ->references('id') // permission id
+             ->references('uuid') // permission id
            ->on($tableNames['permissions'])
            ->onDelete('cascade');
//...

    Schema::create($tableNames['model_has_roles'], function (Blueprint $table) use ($tableNames, $columnNames) {
-         $table->unsignedBigInteger($pivotRole);
+         $table->uuid($pivotRole);
//...
        $table->foreign($pivotRole)
-             ->references('id') // role id
+             ->references('uuid') // role id
            ->on($tableNames['roles'])
            ->onDelete('cascade');//...

    Schema::create($tableNames['role_has_permissions'], function (Blueprint $table) use ($tableNames) {
-         $table->unsignedBigInteger($pivotPermission);
-         $table->unsignedBigInteger($pivotRole);
+         $table->uuid($pivotPermission);
+         $table->uuid($pivotRole);

         $table->foreign($pivotPermission)
-             ->references('id') // permission id
+             ->references('uuid') // permission id
            ->on($tableNames['permissions'])
            ->onDelete('cascade');

         $table->foreign($pivotRole)
-             ->references('id') // role id
+             ->references('uuid') // role id
            ->on($tableNames['roles'])
            ->onDelete('cascade'); 

```

--------------------------------

### Assign Role to Permission

Source: https://spatie.be/docs/laravel-permission/v6/best-practices/performance

Use this method for better performance when frequently adding and deleting permissions.

```php
$permission->assignRole($role)
```

--------------------------------

### Convert permission IDs from strings to integers

Source: https://spatie.be/docs/laravel-permission/v6/upgrading

Use this collection mapping to ensure permission IDs are treated as integers, preventing lookup errors in v6.

```php
collect($validated['permission'])->map(fn($val)=>(int)$val)
```

--------------------------------

### Register Controller Middleware in Laravel 11

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/middleware

Implement the HasMiddleware interface and return an array of middleware definitions from the static middleware method.

```php
public static function middleware(): array
{
    return [
        // examples with aliases, pipe-separated names, guards, etc:
        'role_or_permission:manager|edit articles',
        new Middleware('role:author', only: ['index']),
        new Middleware(\Spatie\Permission\Middleware\RoleMiddleware::using('manager'), except:['show']),
        new Middleware(\Spatie\Permission\Middleware\PermissionMiddleware::using('delete records,api'), only:['destroy']),
    ];
}
```

--------------------------------

### Query Users by Permission Scopes

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/basic-usage

Filter users based on their permissions, including those inherited from roles.

```php
$users = User::permission('edit articles')->get(); // Returns only users with the permission 'edit articles' (inherited or directly)
$usersWhoCannotEditArticles = User::withoutPermission('edit articles')->get(); // Returns all users without the permission 'edit articles' (inherited or directly)
```

--------------------------------

### Extend the Passport Client model

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/passport

Create a custom Client model that implements AuthorizableContract and uses the HasRoles trait. You must define either a $guard_name property or a guardName() method.

```php
use Illuminate\Contracts\Auth\Access\Authorizable as AuthorizableContract;
use Illuminate\Foundation\Auth\Access\Authorizable;
use Laravel\Passport\Client as BaseClient;
use Spatie\Permission\Traits\HasRoles;

class Client extends BaseClient implements AuthorizableContract
{
    use HasRoles;
    use Authorizable;

    public $guard_name = 'api';

    // or

    public function guardName()
    {
        return 'api';
    }
}
```

--------------------------------

### Retrieving Role Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/role-permissions

Access the collection of permissions associated with a role.

```php
// get collection
$role->permissions;

// return only the permission names:
$role->permissions->pluck('name');

// count the number of permissions assigned to a role
count($role->permissions);
// or
$role->permissions->count();
```

--------------------------------

### Adjusting Migration String Lengths

Source: https://spatie.be/docs/laravel-permission/v6/prerequisites

Use these modifications in your migration files if your database engine imposes strict index length limits.

```php
    $table->string('name');       // For MyISAM use string('name', 225); // (or 166 for InnoDB with Redundant/Compact row format)
    $table->string('guard_name'); // For MyISAM use string('guard_name', 25);
```

--------------------------------

### Specify version in composer.json

Source: https://spatie.be/docs/laravel-permission/v6/upgrading

Update the package version constraint in your composer.json file.

```json
^6.0
```

--------------------------------

### Clear Cache During Database Seeding

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/testing

Use an event listener for DatabaseRefreshed to seed roles and permissions and clear the cache after the database is refreshed.

```php
Event::listen(DatabaseRefreshed::class, function () {
    $this->artisan('db:seed', ['--class' => RoleAndPermissionSeeder::class]);
    $this->app->make(\Spatie\Permission\PermissionRegistrar::class)->forgetCachedPermissions();
});
```

--------------------------------

### Check permissions with Blade directives

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/blade-directives

Use standard Laravel @can directives or the package-specific @haspermission directive to verify user access.

```blade
@can('edit articles')
  //
@endcan
```

```blade
@if(auth()->user()->can('edit articles') && $some_other_condition)
  //
@endif
```

```blade
@can('edit articles', 'guard_name')
  //
@endcan
```

--------------------------------

### Check Permission for a Specific Guard

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/multiple-guards

Verify if a user possesses a permission within the context of a specific guard.

```php
$user->hasPermissionTo('publish articles', 'admin');
```

--------------------------------

### Register Controller Middleware in Laravel 10 and Older

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/middleware

Apply middleware within the controller constructor using the $this->middleware method.

```php
public function __construct()
{
    // examples:
    $this->middleware(['role:manager','permission:publish articles|edit articles']);
    $this->middleware(['role_or_permission:manager|edit articles']);
    // or with specific guard
    $this->middleware(['role_or_permission:manager|edit articles,api']);
}
```

--------------------------------

### Register Middleware Aliases in Laravel 11+

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/middleware

Register role and permission middleware aliases within the bootstrap/app.php file for Laravel 11 and newer.

```php
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
            'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
            'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
        ]);
    })
```

--------------------------------

### Use Pipe Operator for Multiple Roles or Permissions

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/middleware

Use the pipe character to specify multiple roles or permissions, acting as an OR condition.

```php
Route::group(['middleware' => ['role:manager|writer']], function () { ... });
Route::group(['middleware' => ['permission:publish articles|edit articles']], function () { ... });
Route::group(['middleware' => ['role_or_permission:manager|edit articles']], function () { ... });

// for a specific guard
Route::group(['middleware' => ['permission:publish articles|edit articles,api']], function () { ... });
```

--------------------------------

### Configure Cache Expiration for Tests

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/testing

Set the cache expiration time to 1 second in the test suite TestCase to reduce the impact of the package's caching infrastructure.

```php
'permission.cache.expiration_time' = \DateInterval::createFromDateString('1 seconds')
```

--------------------------------

### Flush Cache in Seeder

Source: https://spatie.be/docs/laravel-permission/v6/advanced-usage/seeding

Clears the package cache to prevent conflicts during seeding operations.

```php
// reset cached roles and permissions
app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();
```

--------------------------------

### Check for all roles

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/blade-directives

Use @hasallroles to verify that a user possesses every role in the provided list.

```blade
@hasallroles($collectionOfRoles)
    I have all of these roles!
@else
    I do not have all of these roles...
@endhasallroles
// or
@hasallroles('writer|admin')
    I am both a writer and an admin!
@else
    I do not have all of these roles...
@endhasallroles
```

--------------------------------

### Check for any role in a list

Source: https://spatie.be/docs/laravel-permission/v6/basic-usage/blade-directives

Use @hasanyrole to check if a user possesses at least one role from a collection or pipe-separated string.

```blade
@hasanyrole($collectionOfRoles)
    I have one or more of these roles!
@else
    I have none of these roles...
@endhasanyrole
// or
@hasanyrole('writer|admin')
    I am either a writer or an admin or both!
@else
    I have none of these roles...
@endhasanyrole
```
Tokens:
Raw