Laravel Permission

https://spatie.be/docs/laravel-permission/v7
Admin
Laravel Permission is a package that allows you to manage user permissions and roles in a database,...
Tokens:18,114
Snippets:284
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initial Project Setup and Package Installation

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

Commands to initialize 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;\
    use \\Spatie\\Permission\\Traits\\HasRoles;/' app/Models/User.php
sed -i '' $'s/use HasApiTokens, HasFactory, Notifiable;/use HasApiTokens, HasFactory, Notifiable;\
    use \\Spatie\\Permission\\Traits\\HasRoles;/' app/Models/User.php
git add . && git commit -m "Add HasRoles trait"
```

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

### Adding Laravel UI Authentication Scaffolding

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

Commands to install and configure basic authentication scaffolding for testing purposes when no starter kit is used.

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

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

### Implement RolesAndPermissionsSeeder

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

A complete seeder example demonstrating cache clearing, permission creation, and role assignment.

```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());
    }
}
```

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

### Seed permissions using DB::insert

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

This example demonstrates manual insertion of permissions and role associations. Note that it hard-codes table names and bypasses the package's cache-control features.

```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
```

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

### Assign Super-Admin Role on Team Creation

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

Example of using the model boot method to automatically assign a Super Admin 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);
        });
    }
    // ...
```

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

### Check installed package version

Source: https://spatie.be/docs/laravel-permission/v7/advanced-usage/timestamps

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

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

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

### Install package via Composer

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

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

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

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

### Clear Permission Cache in Test Setup

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

Use this in a test class setUp method to ensure roles and permissions are re-registered after test-specific data creation.

```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();
    }
```

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

### Run migrations

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

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

```bash
 php artisan migrate
```

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

### Create Roles with Permissions

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

Create a role and link permissions simultaneously using a pipe-separated string.

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

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

### Display Roles and Permissions

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

List all roles and permissions in a console table.

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

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

### Creating permissions with optimized methods

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

Use these methods instead of Permission::create for better performance on large databases.

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

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

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

### Publish configuration and migrations

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

Publishes the package's migration files and the config/permission.php configuration file.

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

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

### Implement Super Admin via Policy before()

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

Define this method within specific 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.
}
```

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

### Package Methods Supporting BackedEnums

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

List of common package methods that natively support passing BackedEnum instances.

```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 Roles with Team IDs

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

Demonstrates creating global roles by omitting the team_id, or team-specific roles by providing a specific 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']);
```

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

### Configure permission settings for Passport

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

Enable client credentials support in the package configuration file.

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

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

### Create Roles and Permissions via Artisan

Source: https://spatie.be/docs/laravel-permission/v7/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
```

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

### Implement Super Admin via Gate::before

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

Use this in a Service Provider to implicitly grant all permissions to the Super Admin role for gate-related checks.

```php
use Illuminate\Support\Facades\Gate;
// ...
public function boot(): void
{
    // 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;
    });
}
```

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

### Enable Wildcard Permissions

Source: https://spatie.be/docs/laravel-permission/v7/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,
```

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

### Generate Role and Permission models

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

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

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

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

### Enable Teams in Configuration

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

Set the teams feature to true in the permission configuration file.

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

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

### Implement Super Admin via Gate::after

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

Use this in a service provider to handle Super Admin checks after other authorization logic, useful for enforcing specific restrictions.

```php
// somewhere in a service provider

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

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

### Create migration for custom fields

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

Generate a migration file to add new columns to the permissions and roles tables.

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

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

### Define migration schema for custom fields

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

Implement the up method in the migration to add nullable description fields to the database 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();
    });
}
```

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

### Create Guard-Specific Roles and Permissions

Source: https://spatie.be/docs/laravel-permission/v7/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']);
```

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

### Syncing Direct Permissions

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

Replace all existing direct permissions with a new set.

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

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

### Applying Middleware via Static Methods

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

Use the static 'using' method to apply middleware to route groups, accepting either 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 () { ... });
```

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

### Implement Teams Middleware

Source: https://spatie.be/docs/laravel-permission/v7/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);
    }
}
```

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

### Create Roles and Permissions

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

Roles and permissions are standard Eloquent models that require a name attribute.

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

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

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

### Assign roles and permissions

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

Use these methods on user or role instances to grant access rights.

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

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

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

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

### Registering Controller Middleware

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

Implement the HasMiddleware interface in your controller to define middleware via 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']),
    ];
}
```

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

### Assign Wildcard Permissions

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

Assigning a permission with an asterisk allows all actions within that scope.

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

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

### Available Events in v7.0.0+

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

List of event classes available for role and permission operations since version 7.0.0.

```php
\Spatie\Permission\Events\RoleAttachedEvent::class
\Spatie\Permission\Events\RoleDetachedEvent::class
\Spatie\Permission\Events\PermissionAttachedEvent::class
\Spatie\Permission\Events\PermissionDetachedEvent::class
```

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

### Register Middleware Priority

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

Ensure the custom middleware runs before SubstituteBindings in the AppServiceProvider.

```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,
        );
    }
}
```

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

### Syncing User Roles

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

Replace all existing 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']);
```

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

### Configure User Model for Multiple Guards

Source: https://spatie.be/docs/laravel-permission/v7/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']; }
```

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

### Implement custom Gate::before logic

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

Define a custom permission check in the boot method of your AppServiceProvider. Ensure the register_permission_check_method config is set to false to bypass default behavior.

```php
use Illuminate	Support	Facades	Gate;

public function boot(): void
{
    ...

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

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

### Use OR Logic in Middleware

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

Use the pipe character to specify multiple roles or permissions that satisfy the middleware requirement.

```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 () { ... });
```

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

### Manual Cache Reset Methods

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

Reset the package cache manually using the PermissionRegistrar or the provided Artisan command.

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

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

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

### Retrieve Users and Roles

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

Common Eloquent queries to fetch users with their associated roles or permissions, and to filter 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/v7/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']);
```

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

### Checking Permissions by ID

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

Verify permissions using integer IDs instead of permission names.

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

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

### Managing Role Permissions

Source: https://spatie.be/docs/laravel-permission/v7/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']);
```

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

### Checking Multiple Permissions

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

Verify if a user has any or all of the provided permissions.

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

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

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

### Register Package Middleware Aliases

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

Register the package's role and permission middleware aliases in the application bootstrap configuration.

```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,
        ]);
    })
```

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

### Assign Direct Permissions to Users

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

Assigning roles and specific permissions directly to a user instance.

```php
$role = Role::findByName('writer');
$role->givePermissionTo('edit articles');

$user->assignRole('writer');

$user->givePermissionTo('delete articles');
```

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

### Authorize Using Enums

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

Most package methods accept Enums directly, but you can use enum_value() or ->value for manual fallback when necessary.

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

// Blade directives:
@can(enum_value(PermissionsEnum::VIEWPOSTS))
```

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

### Examine User Permissions

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

Retrieve collections of direct, inherited, or all permissions for a user.

```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();
```

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

### Configure Custom Team Foreign Key

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

Define a custom foreign key for teams within the permission configuration file.

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

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

### Assigning a role to a permission

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

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

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

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

### Apply Middleware to Routes

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

Use registered middleware aliases to protect routes based on roles, permissions, or specific guards.

```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 () { ... });
```

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

### Assign roles in Seeder without Factory States

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

Iterate over created models to assign roles after bulk insertion.

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

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

### Automatic Cache Refreshing via Built-in Methods

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

Use these methods to manipulate roles and permissions while ensuring the cache is automatically updated.

```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);
```

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

### Register the custom Client model

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

Instruct Passport to use your extended Client model by calling Passport::useClientModel in the boot method of your AuthServiceProvider.

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

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

### Check Direct Permissions

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

Verify if a user has specific, all, or any direct permissions assigned.

```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']);
```

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

### Create Roles with Team IDs

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

Create roles associated with a specific team ID when teams are enabled.

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

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

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

### Query Roles and Permissions for Other Teams

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

Required steps to switch the active team context and clear cached model relations before querying roles or 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
```

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

### Checking Multiple Permissions by ID

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

Verify if a user has any of the provided permissions using a mix of names and IDs.

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

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

### Sync Permissions and Roles

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

Use sync methods to update the collection of permissions or roles associated with an entity.

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

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

### Reset Package Cache

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

Manually clear the cached roles and permissions.

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

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

### Define a Role Enum

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

Create a BackedEnum to represent application roles, optionally including helper methods for labels.

```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',
        };
    }
}
```

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

### Check Wildcard Permissions

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

Verify if a user has access to specific actions when a wildcard permission is assigned.

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

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

### Use Subparts in Permissions

Source: https://spatie.be/docs/laravel-permission/v7/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');
```

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

### Bulk insert permissions

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

Use Eloquent's insert method to bypass internal package checks for faster seeding of large datasets.

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

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

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

### Customize UnauthorizedException rendering

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

Use the withExceptions method to define a custom JSON response for UnauthorizedException instances.

```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,
        ]);
    });
}
```

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

### Define Wildcard Permission String

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

Wildcard permissions are represented as dot-separated strings.

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

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

### Flexible Model Assignment Inputs

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

Methods accept various input types including models, IDs, arrays, and collections.

```php
$role->assignToModels($user);                  // a single model
$role->assignToModels($user->id);              // a single ID
$role->assignToModels([1, 2, 3]);              // an array of IDs
$role->assignToModels(User::query()->get());   // a Collection
$role->assignToModels([$user1, 5, $user2]);    // mixed
```

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

### Clear configuration cache

Source: https://spatie.be/docs/laravel-permission/v7/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
```

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

### Managing Role-to-Model Assignments

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

Assign, remove, or sync roles directly from the role instance.

```php
$role = Role::findByName('writer');

// Give the role to two users at once.
$role->assignToModels([$user1, $user2]);

// Remove it from one user.
$role->removeFromModels($user1);

// Replace every model that currently has this role with a new set.
$role->syncModels([$user2, $user3]);
```

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

### Adjusting Migration String Lengths

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

Use these explicit length settings in your migration files to accommodate database index limitations.

```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);
```

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

### Configuring Model Classes for IDs

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

Specify the model class when assigning roles via raw IDs.

```php
$role->assignToModels([1, 2, 3], User::class);
```

```php
'models' => [
    // ...
    'default_model' => App\\Models\\User::class,
],
```

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

### Granting Direct Permissions

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

Assign one or more permissions to a user using strings or arrays.

```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']);
```

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

### Assign Permissions to Roles

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

Permissions can be assigned to roles or roles can be assigned to permissions.

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

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

### Checking User Roles

Source: https://spatie.be/docs/laravel-permission/v7/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']);
```

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

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

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

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

### Create Roles and Permissions with Enums

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

Use the enum_value() helper function when creating roles or permissions to ensure the underlying string value is passed to Eloquent.

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

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

### Filter Users by Permission

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

Use the permission and withoutPermission scopes to filter users based on their permissions.

```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)
```

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

### Assign roles via Factory States

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

Assign roles automatically during model creation using the afterCreating hook in a factory state.

```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();
```

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

### Checking Permissions with Gate

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

Use Laravel's native can function to check permissions, which supports Super-Admin features.

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

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

### Check Multiple Roles

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

Verify if a user has any or all roles 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
```

```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
```

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

### Checking Permissions via hasPermissionTo

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

Verify if a user has a specific permission. Note that this does not support Super-Admin functionality.

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

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

### Check Permissions with Blade Directives

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

Use standard Laravel @can directives or package-specific @haspermission directives 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
```

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

### Extend the Passport Client model

Source: https://spatie.be/docs/laravel-permission/v7/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';
    }
}
```

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

### Configure Cache Expiration for Tests

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

Set a short cache lifetime in your test suite TestCase to reduce the impact of the package's caching infrastructure.

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

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

### Retrieve Role Permissions

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

Methods to access and count 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();
```

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

### Clear Cache During Database Seeding

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

Register 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();
});
```

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

### Update model morph key in configuration

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

Change the model_morph_key in the permission.php configuration file to reflect the use of UUIDs.

```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',
        ],
```

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

### Check Role Negation and Exact Match

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

Use @unlessrole to check for the absence of a role or @hasexactroles to verify a user has exactly the specified roles.

```blade
@unlessrole('does not have this role')
    I do not have the role
@else
    I do have the role
@endunlessrole
```

```blade
@hasexactroles('writer|admin')
    I am both a writer and an admin and nothing else!
@else
    I do not have all of these roles or have more other roles...
@endhasexactroles
```

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

### Check Permission for a Specific Guard

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

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

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

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

### Flush cache manually

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

Use this to clear cached roles and permissions to avoid conflicts during seeding.

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

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

### Count Users by Role

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

Filters the collection of users to count those who possess a specific role.

```php
$managersCount = User::with('roles')->get()->filter(
    fn ($user) => $user->roles->where('name', 'Manager')->toArray()
)->count();
```

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

### Use Default Laravel Authorization Middleware

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

Apply Laravel's built-in Authorize middleware to route groups for permission checks.

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

// or with static method
Route::group(['middleware' => [\Illuminate\Auth\Middleware\Authorize::using('publish articles')]], function () { ... });
```
Tokens:
Raw