Laravel Permission

https://github.com/spatie/laravel-permission
Admin
This package allows you to manage user permissions and roles in a database for Laravel applications.
Tokens:67,518
Snippets:563
Trust Score:10
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Initial setup commands for demo app

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/new-app.md

Commands to create a new Laravel project, install the spatie/laravel-permission package, and add the HasRoles trait to the User model. Includes optional git and environment setup steps.

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

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

### Setup Laravel UI auth scaffold

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/new-app.md

Commands to install Laravel UI and generate Bootstrap authentication scaffolding, useful for testing roles and permissions with a demo user.

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

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

### Clear Permission Cache in Test setUp()

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/testing.md

Add this setUp() method to your test class to re-register permissions by clearing the permission cache. Use it when you are not seeding roles and permissions in setUp() and encounter a chicken/egg situation where roles and permissions aren't 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 spatie/laravel-permission via Composer

Source: https://github.com/spatie/laravel-permission/blob/main/docs/installation-laravel.md

Install the package via Composer. The Service Provider is automatically registered, but you can manually add it to bootstrap/providers.php if needed.

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

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

### Apply Middleware via Static using Method

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/middleware.md

Shows how to apply the role, permission, and role-or-permission middleware using the static `using` method. Each example imports the corresponding middleware class and passes either a string or an array to `using`. The `|`-separated string is used for multiple permissions.

```php
use Spatie\Permission\Middleware\RoleMiddleware;
Route::middleware(RoleMiddleware::using('manager'))
```

```php
use Spatie\Permission\Middleware\PermissionMiddleware;
Route::middleware(
    PermissionMiddleware::using('publish articles|edit articles')
)
```

```php
use Spatie\Permission\Middleware\RoleOrPermissionMiddleware;
Route::middleware(
    RoleOrPermissionMiddleware::using(['manager', 'edit articles'])
)
```

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

### Enable teams in config/permission.php

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/teams-permissions.md

Set 'teams' to true in the permission config file to enable teams permissions. Must be done before running migrations when first installing the package.

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

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

### Example permission string with dot-separated parts

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/wildcard-permissions.md

A wildcard permission string is composed of one or more parts separated by dots. This example shows a typical three-part string representing {resource}.{action}.{target}.

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

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

### Example Team Middleware for setting team ID

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/teams-permissions.md

Middleware that sets the global team ID from the session or a custom method. Must be registered before SubstituteBindings to avoid 404 errors.

```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 permissions and roles for multiple guards and check permission

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/multiple-guards.md

Create roles and permissions with an explicit guard, and then check a user's permission for a specific guard. The first block shows how to create different permissions with the same name for different guards. The second block is a subsequent example that checks permission for the 'admin' guard, directly related to the previous creation.

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

```

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

```

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

### Assign permissions and roles to users

Source: https://github.com/spatie/laravel-permission/blob/main/README.md

Shows how to give a permission directly to a user, assign a role, and give a permission to a role. Use these methods after installing the package.

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

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

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

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

### Example RolesEnum class

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/enums.md

Defines a string-backed enum for roles with a label() helper method. Use this as a template for role and permission enums.

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

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

### Get permissions for a user

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/basic-usage.md

Retrieve permissions directly assigned, via roles, or all permissions for a user. Also get role names.

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

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

### Check any permission by ID with hasAnyPermission

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/direct-permissions.md

Pass integers to `hasAnyPermission` to check by permission ID. This example mixes string names and integer IDs.

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

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

### Extend Spatie Role model

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/extending.md

Example of extending the Spatie\Permission\Models\Role model. You must update config/permission.php to specify your namespaced model.

```php
<?php
namespace App\Models;
use Spatie\Permission\Models\Role as SpatieRole;

class Role extends SpatieRole
{
    // You might set a public property like guard_name or connection, or override other Eloquent Model methods/properties
}
```

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

### PostPolicy with permission checks for view, create, update, delete

Source: https://github.com/spatie/laravel-permission/blob/main/docs/best-practices/using-policies.md

Example PostPolicy for the spatie/laravel-permission package. Use it to centralize access control for Post records. The view method allows published posts to all users (including guests), checks permissions for viewing unpublished posts, and allows authors to view their own unpublished posts. The create method checks the 'create posts' permission. The update and delete methods allow users with 'edit all posts' or 'delete any post' permissions to act on any post, and users with 'edit own posts' or 'delete own posts' to act on their own posts.

```php
<?php
namespace App\Policies;

use App\Models\Post;
use App\Models\User;
use Illuminate\Auth\Access\HandlesAuthorization;

class PostPolicy
{
    use HandlesAuthorization;

    public function view(?User $user, Post $post): bool
    {
        if ($post->published) {
            return true;
        }

        // visitors cannot view unpublished items
        if ($user === null) {
            return false;
        }

        // admin overrides published status
        if ($user->can('view unpublished posts')) {
            return true;
        }

        // authors can view their own unpublished posts
        return $user->id == $post->user_id;
    }

    public function create(User $user): bool
    {
        return $user->can('create posts');
    }

    public function update(User $user, Post $post): bool
    {
        if ($user->can('edit all posts')) {
            return true;
        }

        if ($user->can('edit own posts')) {
            return $user->id == $post->user_id;
        }
    }

    public function delete(User $user, Post $post): bool
    {
        if ($user->can('delete any post')) {
            return true;
        }

        if ($user->can('delete own posts')) {
            return $user->id == $post->user_id;
        }
    }
}
```

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

### Check direct permissions with hasDirectPermission, hasAllDirectPermissions, hasAnyDirectPermission

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/role-permissions.md

Checks whether a user has specific, all, or any of a set of direct permissions. In the preceding example, hasAllDirectPermissions returns false because 'edit articles' is not direct, while hasAnyDirectPermission returns true.

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

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

### Policy: Using $user->can() in PostPolicy::update

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Example policy method using $user->can() to check permissions. Grants update if the user can edit all posts, or if they can edit own posts and own the post.

```php
class PostPolicy
{
    public function update(User $user, Post $post): bool
    {
        if ($user->can('edit all posts')) {
            return true;
        }

        return $user->can('edit own posts') && $user->id === $post->user_id;
    }
}
```

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

### Check permission by ID with hasPermissionTo

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/direct-permissions.md

Pass an integer representing the permission ID to `hasPermissionTo`. Examples show passing a literal ID, a permission's ID from a model, or a variable.

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

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

### Force single guard with getDefaultGuardName

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/multiple-guards.md

Override the default guard name in your User model to force the use of a single guard, so roles and permissions only need to be created for that one guard. The example uses 'web'.

```php
    protected string $guard_name = 'web';
    protected function getDefaultGuardName(): string { return $this->guard_name; }

```

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

### Super Admin: Gate::before in AppServiceProvider::boot()

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Define a Gate::before callback in AppServiceProvider::boot() to grant Super Admin users all abilities. Must return null (not false) to allow normal checks for other users.

```php
use Illuminate\Support\Facades\Gate;

public function boot(): void
{
    Gate::before(function ($user, $ability) {
        return $user->hasRole('Super Admin') ? true : null;
    });
}
```

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

### Create PermissionsDemoSeeder and run it

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/new-app.md

Creates a seeder that resets cached permissions, creates four permissions, three roles (writer, admin, Super-Admin), and three demo users with assigned roles. Run this seeder after creating the file to populate the database.

```php
<?php

namespace Database\Seeders;

use Illuminate\Database\Seeder;
use Spatie\Permission\Models\Permission;
use Spatie\Permission\Models\Role;
use Spatie\Permission\PermissionRegistrar;

class PermissionsDemoSeeder extends Seeder
{
    /**
     * Create the initial roles and permissions.
     */
    public function run(): void
    {
        // Reset cached roles and permissions
        app()[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']);

        // create roles and assign existing permissions
        $role1 = Role::create(['name' => 'writer']);
        $role1->givePermissionTo('edit articles');
        $role1->givePermissionTo('delete articles');

        $role2 = Role::create(['name' => 'admin']);
        $role2->givePermissionTo('publish articles');
        $role2->givePermissionTo('unpublish articles');

        $role3 = Role::create(['name' => 'Super-Admin']);
        // gets all permissions via Gate::before rule; see AuthServiceProvider

        // create demo users
        $user = \App\Models\User::factory()->create([
            'name' => 'Example User',
            'email' => 'tester@example.com',
        ]);
        $user->assignRole($role1);

        $user = \App\Models\User::factory()->create([
            'name' => 'Example Admin User',
            'email' => 'admin@example.com',
        ]);
        $user->assignRole($role2);

        $user = \App\Models\User::factory()->create([
            'name' => 'Example Super-Admin User',
            'email' => 'superadmin@example.com',
        ]);
        $user->assignRole($role3);
    }
}

```

```sh
php artisan migrate:fresh --seed --seeder=PermissionsDemoSeeder
```

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

### Get role permissions collection

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/role-permissions.md

Access the $role->permissions property to get a collection of all related permission objects. The collection supports Eloquent Collection operations like pluck and count.

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

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

### Package methods supporting BackedEnums

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/enums.md

Lists all package methods that accept BackedEnum parameters directly, covering creation, assignment, permission checks, and role checks.

```php
    // Creating
    app(Role::class)->create(['name' => RolesEnum::WRITER]);
    app(Role::class)->findByName(RolesEnum::WRITER);
    app(Role::class)->findOrCreate(RolesEnum::WRITER);

    app(Permission::class)->create(['name' => PermissionsEnum::EDITPOSTS]);
    app(Permission::class)->findByName(PermissionsEnum::EDITPOSTS);
    app(Permission::class)->findOrCreate(PermissionsEnum::EDITPOSTS);

	$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 with Permission::create()

Source: https://github.com/spatie/laravel-permission/blob/main/docs/best-practices/performance.md

Standard way to create a permission. May be slower on large databases due to package protections.

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

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

### Create Role and Permission models with artisan

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/uuid.md

Run these artisan commands to generate new Role and Permission model files. These models will be extended to use UUIDs.

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

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

### Create Role and Permission models

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/basic-usage.md

Create a Role and a Permission model by providing a name. Both are regular Eloquent models.

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

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

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

### Create and assign wildcard permission 'posts.*'

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/wildcard-permissions.md

Creates and assigns a wildcard permission 'posts.*' which is equivalent to the permission 'posts'. This grants all actions on posts. The permission must be created before it can be assigned.

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

```php
Permission::create(['name'=>'posts']);
$user->givePermissionTo('posts');
```

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

### Policy before() method for Super Admin

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/super-admin.md

Alternative to Gate::before for granting super-admin control in individual Policy classes. Must return null when the user is not a Super Admin to avoid blocking other policies.

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

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

### Enable teams in config/permission.php

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Configuration option to enable multi-tenancy (teams) in config/permission.php. Must be set before running migrations.

```php
'teams' => true,
```

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

### Use blade @role directive with multiple guards

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/multiple-guards.md

Use blade directives with multiple guards by passing the guard as the second argument. In this example, the 'admin' guard is specified for the @role directive.

```php
@role('super-admin', 'admin')
    I am a super-admin!
@else
    I am not a super-admin...
@endrole

```

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

### Run migrations with artisan migrate

Source: https://github.com/spatie/laravel-permission/blob/main/docs/installation-laravel.md

Run the migrations to create the tables for this package after the config and migration have been published and configured.

```bash
php artisan migrate
```

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

### Create a role with linked permissions

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Creates a role named 'writer' for the 'web' guard and links permissions 'create articles' and 'edit articles' to it.

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

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

### Create permission with Permission::make() and saveOrFail()

Source: https://github.com/spatie/laravel-permission/blob/main/docs/best-practices/performance.md

Faster alternative to Permission::create() on large databases. Uses Permission::make() followed by saveOrFail().

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

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

### Show roles and permissions table

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Displays a table of roles and permissions per guard.

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

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

### Enable use_passport_client_credentials config

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/passport.md

Update config/permission.php to set 'use_passport_client_credentials' to true, ensuring the right checks are performed for the Client Credentials Grant.

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

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

### Link local repository and push initial code

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/new-app.md

Adds the remote origin and pushes the main branch to GitHub. This only needs to be done once.

```sh
git remote add origin git@github.com:YOURUSERNAME/REPONAME.git
git push -u origin main
```

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

### Create a permission with artisan

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Creates a permission named 'edit articles' using the default guard.

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

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

### Create a role with artisan

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Creates a role named 'writer' using the default guard.

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

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

### Run package tests with Composer

Source: https://github.com/spatie/laravel-permission/blob/main/README.md

Runs the package's test suite using Composer. Useful for contributors.

```bash
composer test
```

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

### Config: Enable wildcard permission

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/wildcard-permissions.md

Set 'enable_wildcard_permission' to true in the permission config file to enable wildcard permissions.

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

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

### Retrieve direct, role, and all permissions with getDirectPermissions, getPermissionsViaRoles, getAllPermissions

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/role-permissions.md

Retrieves the user's direct permissions, permissions inherited from roles, and all applicable permissions. Each returns a collection of Spatie\Permission\Models\Permission objects.

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

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

### Create migration for adding description field

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/extending.md

Run this artisan command to generate a migration for adding a 'description' field to the permissions and roles tables.

```sh
php artisan make:migration add_description_to_permissions_tables
```

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

### Subparts: combined resources and actions

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/wildcard-permissions.md

Subparts separated by commas allow complex permission schemes. 'posts,users.create,update,view' grants create, update, view on both posts and users. '*.create,update,view' grants those actions on any resource. 'posts.*.1,4,6' grants any action on posts with ids 1, 4, and 6. Remember: the meaning of each part is application-defined.

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

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

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

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

### Use Role and Permission Middleware in Routes

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Apply permission and role middleware in routes. Use pipe `|` for OR logic. Optionally specify a guard after the role or permission name (e.g., `role:manager,api`).

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

// With specific guard
Route::middleware(['role:manager,api'])->group(function () { ... });
```

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

### Add and commit changes, then push to GitHub

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/new-app.md

Stages all changes, creates a commit with a message, and pushes to the remote main branch. Repeat whenever you change code you want to share.

```sh
git add .
git commit -m "Explain what your commit is about here"
git push origin main
```

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

### Sync permissions to a role

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/basic-usage.md

Sync multiple permissions to a role using syncPermissions or syncRoles.

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

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

### Publish migration and config with artisan vendor:publish

Source: https://github.com/spatie/laravel-permission/blob/main/docs/installation-laravel.md

Publish the migration and config/permission.php config file. If you already have a config/permission.php file, you must rename or remove it before publishing.

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

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

### Checking Roles and Permissions with Gates and Package Methods

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Use the Gate-based `can()` and `canAny()` methods for authorization checks to support Super Admin bypass. The package methods (`hasPermissionTo`, `hasAnyPermission`, etc.) bypass the Gate and do not consider Super Admin. Role checks include exact match via `hasExactRoles`.

```php
// Permission checks (preferred - supports Super Admin via Gate)
$user->can('edit articles');
$user->canAny(['edit articles', 'delete articles']);

// Direct package methods (bypass Gate, no Super Admin support)
$user->hasPermissionTo('edit articles');
$user->hasAnyPermission(['edit articles', 'publish articles']);
$user->hasAllPermissions(['edit articles', 'publish articles']);
$user->hasDirectPermission('edit articles');

// Role checks
$user->hasRole('writer');
$user->hasAnyRole(['writer', 'editor']);
$user->hasAllRoles(['writer', 'editor']);
$user->hasExactRoles(['writer', 'editor']);

// Get assigned roles and permissions
$user->getRoleNames();           // Collection of role name strings
$user->getPermissionNames();     // Collection of permission name strings
$user->getDirectPermissions();   // Direct permissions only
$user->getPermissionsViaRoles(); // Inherited via roles
$user->getAllPermissions();      // Both direct and inherited
```

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

### Register Middleware Aliases in bootstrap/app.php

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Register middleware aliases in `bootstrap/app.php` for the `role`, `permission`, and `role_or_permission` middleware.

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

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

### Migration to add description field to permissions and roles tables

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/extending.md

In the generated migration file, add a nullable string column 'description' to both 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();
    });
}
```

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

### Create a role with team ID

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Creates a role with a team ID. The first command uses the default guard, the second specifies the 'api' guard.

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

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

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

### Run Permission Lookup Benchmark with Default Count

Source: https://github.com/spatie/laravel-permission/blob/main/tests/Benchmarks/README.md

Runs the benchmark with the default BENCH_COUNT. Use the same PHP binary, Composer lock file, cache driver, and benchmark file for both revisions. Disable coverage and Xdebug, run revisions sequentially, and repeat to check for machine noise.

```sh
CACHE_DRIVER=array vendor/bin/pest tests/Benchmarks/PermissionLookup.php
```

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

### Create roles and permissions with Spatie Laravel Permission

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Create roles and permissions using the create method or the idempotent findOrCreate method, which is safe for seeders. The guard name 'web' is specified in findOrCreate.

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

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

// findOrCreate is idempotent (safe for seeders)
$role = Role::findOrCreate('writer', 'web');
$permission = Permission::findOrCreate('edit articles', 'web');
```

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

### Creating roles and permissions using enums

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/enums.md

Shows how to pass BackedEnum values directly to create, findByName, and findOrCreate methods for roles and permissions. Uses Laravel's enum_value() function under the hood.

```php
$role = app(Role::class)->create(['name' => RolesEnum::WRITER]);
$role = app(Role::class)->findByName(RolesEnum::WRITER);
$role = app(Role::class)->findOrCreate(RolesEnum::WRITER);

$permission = app(Permission::class)->create(['name' => PermissionsEnum::EDITPOSTS]);
$permission = app(Permission::class)->findByName(PermissionsEnum::EDITPOSTS);
$permission = app(Permission::class)->findOrCreate(PermissionsEnum::EDITPOSTS);
```

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

### Run Permission Lookup Benchmark with BENCH_COUNT=3000

Source: https://github.com/spatie/laravel-permission/blob/main/tests/Benchmarks/README.md

Runs the benchmark with BENCH_COUNT set to 3000 additional permissions (the fixture already contains five). Use the same PHP binary, Composer lock file, cache driver, and benchmark file for both revisions. Disable coverage and Xdebug, run revisions sequentially, and repeat to check for machine noise.

```sh
CACHE_DRIVER=array BENCH_COUNT=3000 vendor/bin/pest tests/Benchmarks/PermissionLookup.php
```

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

### Apply middleware to routes with role, permission, and role_or_permission

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/middleware.md

Apply role, permission, or role_or_permission middleware to route groups or individual routes. Supports specifying a guard with a comma (e.g., 'role:manager,api') and passing an array of middleware for multiple checks.

```php
// You can apply middleware to a group of routes:
Route::middleware('role:manager')->group(function () {
    // ...
});

// Or, for individual routes, apply the middleware directly:
Route::middleware('role:manager')->get('/admin', ...);
Route::middleware('permission:publish articles')->get('/articles/create', ...);
Route::middleware('role_or_permission:publish articles')->get('/articles/{id}', ...);

// for a specific guard:
Route::middleware('role:manager,api')->get('/api/admin', ...);

// multiple middleware
Route::middleware([
    'role:manager',
    'permission:publish articles'
])->get('/admin/publish', ...);
```

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

### Eloquent calls on roles and permissions

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/basic-usage.md

Use standard Eloquent queries on Role and Permission models, such as with, all, doesntHave, and whereNotIn.

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

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

### App\Model\Permission.php - Extended Permission model with HasUuids

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/uuid.md

This is the content of the 'App\Model\Permission.php' file. It extends the Spatie Permission model, uses the HasUuids trait, and sets the primary key to 'uuid'.

```php
<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Spatie\Permission\Models\Permission as SpatiePermission;

class Permission extends SpatiePermission
{
    use HasFactory;
    use HasUuids;
    protected $primaryKey = 'uuid';
}
```

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

### Register controller middleware with HasMiddleware interface

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/middleware.md

Register controller middleware by implementing the HasMiddleware interface and returning an array from the static middleware() method. Supports alias strings, pipe-separated names, guards, and the RoleMiddleware/PermissionMiddleware classes with only/except options.

```php
use Illuminate\Routing\Controllers\HasMiddleware;
use Illuminate\Routing\Controllers\Middleware;

use Spatie\Permission\Middleware\RoleMiddleware;
use Spatie\Permission\Middleware\PermissionMiddleware;

class ArticleController implements HasMiddleware
{
    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(RoleMiddleware::using('manager'), except:['show']),
            new Middleware(PermissionMiddleware::using('delete records,api'), only:['destroy']),
        ];
    }
}
```

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

### Sync direct permissions for a user

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/direct-permissions.md

Use `syncPermissions` to revoke all existing permissions and add the given ones in one go. This replaces the user's direct permissions with the specified list.

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

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

### Register middleware priority in AppServiceProvider

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/teams-permissions.md

Adds your custom team middleware to the middleware priority before SubstituteBindings to prevent 404 responses when 403 is expected.

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

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

### Create a role for a specific guard

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Creates a role named 'writer' for the 'web' guard.

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

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

### Register package middleware aliases in bootstrap/app.php

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/middleware.md

Register aliases for the package's middleware in /bootstrap/app.php. This allows using 'role', 'permission', and 'role_or_permission' as middleware aliases throughout the app.

```php
// ...
use Spatie\Permission\Middleware\RoleMiddleware;
use Spatie\Permission\Middleware\PermissionMiddleware;
use Spatie\Permission\Middleware\RoleOrPermissionMiddleware;

return Application::configure(basePath: dirname(__DIR__))
    // ...
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'role' => RoleMiddleware::class,
            'permission' => PermissionMiddleware::class,
            'role_or_permission' => RoleOrPermissionMiddleware::class,
        ]);
    })
    // ...
```

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

### Create roles with team_id

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/teams-permissions.md

Shows three ways to create a role with an optional team_id: passing null creates a global role, passing a specific team_id creates a team role, and omitting team_id uses 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']);
```

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

### Seed users and assign roles without factory states

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/seeding.md

Seeds 50 users and assigns the 'Member' role to each one without using factory states. This approach is useful when you need to assign roles after creating users in bulk.

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

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

### Enable events in config/permission.php

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Configuration option to enable events in config/permission.php. When enabled, events like RoleAttachedEvent and PermissionDetachedEvent are fired.

```php
'events_enabled' => true,
```

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

### Apply middleware attributes to controller methods

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/middleware.md

Apply middleware to controller methods using PHP attributes: #[Middleware] with RoleMiddleware::using() and #[Authorize] for permission checks. The only option restricts the middleware to specific methods.

```php
use Illuminate\Routing\Attributes\Controllers\Middleware;
use Illuminate\Routing\Attributes\Controllers\Authorize;

use Spatie\Permission\Middleware\RoleMiddleware;

class ArticleController
{
    #[Middleware(RoleMiddleware::using('manager'), only: ['index'])]
    public function index()
    {
        // ...
    }

    #[Authorize('publish articles')]
    public function store()
    {
        // ...
    }
}
```

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

### App\Model\Role.php - Extended Role model with HasUuids

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/uuid.md

This is the content of the 'App\Model\Role.php' file. It extends the Spatie Role model, uses the HasUuids trait, and sets the primary key to 'uuid'.

```php
<?php
namespace App\Models;

use Illuminate\Database\Eloquent\Concerns\HasUuids;
use Illuminate\Database\Eloquent\Factories\HasFactory;
use Spatie\Permission\Models\Role as SpatieRole;

class Role extends SpatieRole
{
    use HasFactory;
    use HasUuids;
    protected $primaryKey = 'uuid';
}
```

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

### Sync permissions on role with syncPermissions

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/role-permissions.md

Use $role->syncPermissions() to revoke all existing permissions and assign the given list in one go. It accepts an array of permission names.

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

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

### Give direct permissions to a user

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/direct-permissions.md

Use `givePermissionTo` to assign one or multiple permissions to a user. You can pass multiple arguments or an array. This is for direct user permissions, not via roles.

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

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

### Seed permissions with Eloquent insert

Source: https://github.com/spatie/laravel-permission/blob/main/docs/advanced-usage/seeding.md

Uses Eloquent's insert command to seed permissions, bypassing internal checks and extra queries. This speeds up seeding for large data sets.

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

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

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

### Assign a permission to a role

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/basic-usage.md

Assign a permission to a role using either givePermissionTo or assignRole.

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

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

### Assign roles and permissions with Spatie Laravel Permission

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Assign roles to users and permissions to roles. syncRoles and syncPermissions replace all existing assignments. Direct permissions on users are an anti-pattern; assign permissions to roles instead.

```php
// Assign roles to users
$user->assignRole('writer');
$user->assignRole('writer', 'admin');
$user->assignRole(['writer', 'admin']);
$user->syncRoles(['writer', 'admin']); // replaces all
$user->removeRole('writer');

// Assign permissions to roles (preferred)
$role->givePermissionTo('edit articles');
$role->givePermissionTo(['edit articles', 'delete articles']);
$role->syncPermissions(['edit articles', 'delete articles']);
$role->revokePermissionTo('edit articles');

// Reverse assignment
$permission->assignRole('writer');
$permission->syncRoles(['writer', 'editor']);
$permission->removeRole('writer');
```

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

### Enums: RolesEnum and PermissionsEnum with Direct Usage

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Define string-backed enums for roles and permissions, and use them directly with package methods like findOrCreate, assignRole, hasRole, givePermissionTo, and hasPermissionTo.

```php
enum RolesEnum: string
{
    case WRITER = 'writer';
    case EDITOR = 'editor';
}

enum PermissionsEnum: string
{
    case EDIT_POSTS = 'edit posts';
    case DELETE_POSTS = 'delete posts';
}

// Most methods accept enums directly
Permission::findOrCreate(PermissionsEnum::EDIT_POSTS, 'web');
$user->assignRole(RolesEnum::WRITER);
$user->hasRole(RolesEnum::WRITER);
$role->givePermissionTo(PermissionsEnum::EDIT_POSTS);
$user->hasPermissionTo(PermissionsEnum::EDIT_POSTS);
```

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

### Register extended Client model with Passport

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/passport.md

Add this rule to the boot method of your App\Providers\AuthServiceProvider class to tell Passport to use the extended Client model. Replace the namespace with your extended Client's namespace.

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

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

### Create a permission for a specific guard

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Creates a permission named 'edit articles' for the 'web' guard.

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

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

### Use Laravel's Built-in can Middleware for Single Permissions

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

For single permissions, use Laravel's built-in `can` middleware. It works with the Gate and respects Super Admin.

```php
Route::middleware(['can:edit articles'])->group(function () { ... });

```

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

### Assign permission to role with givePermissionTo

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/role-permissions.md

Use $role->givePermissionTo() to assign a permission to a role. It accepts a string permission name or a Permission object.

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

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

### Assign Super Admin Role on Team Creation

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/teams-permissions.md

Use this model event to automatically assign a global 'Super Admin' role to a user when a new team is created. It temporarily switches the package's team context to the new team, assigns the role, then restores the previous team context from the session.

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

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

### Specify multiple roles or permissions with pipe (OR) in route middleware

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/middleware.md

Use the pipe character (|) to specify multiple roles or permissions, treated as OR. The guard can be appended after a comma, as in 'permission:publish articles|edit articles,api'.

```php
Route::middleware('role:manager|writer')
Route::middleware('permission:publish articles|edit articles')
Route::middleware('role_or_permission:manager|edit articles')

// for a specific guard
Route::middleware('permission:publish articles|edit articles,api')
```

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

### Scope users by permission and without permission

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/basic-usage.md

Use the permission and withoutPermission scopes to filter users by permission. Accepts a string, Permission object, or Collection.

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

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

### Reset the permission cache

Source: https://github.com/spatie/laravel-permission/blob/main/docs/basic-usage/artisan.md

Manually resets the cache for the package. It is more efficient to use the built-in API functions instead.

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

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

### Seed roles and permissions with cache flush

Source: https://github.com/spatie/laravel-permission/blob/main/resources/boost/skills/laravel-permission-development/SKILL.md

Seeder that flushes the permission cache before creating permissions and roles. Use this pattern to avoid stale cache issues when seeding.

```php
class RolesAndPermissionsSeeder extends Seeder
{
    public function run(): void
    {
        // Reset cache
        app()[\Spatie\Permission\PermissionRegistrar::class]->forgetCachedPermissions();

        // Create permissions
        Permission::findOrCreate('edit articles', 'web');
        Permission::findOrCreate('delete articles', 'web');

        // Create roles and assign permissions
        Role::findOrCreate('writer', 'web')
            ->givePermissionTo(['edit articles']);

        Role::findOrCreate('admin', 'web')
            ->givePermissionTo(Permission::all());
    }
}
```
Tokens:
Raw