Laravel ACL

https://github.com/yajra/laravel-acl-docs
Admin
Laravel ACL is a simple and lightweight role-based permissions system that integrates with Laravel's...
Tokens:11,718
Snippets:54
Trust Score:9.7
Update:7 months ago
Show doc for...
Tokens:
Raw
### Run Laravel ACL Migrations

Source: https://github.com/yajra/laravel-acl-docs/blob/master/installation.md

Executes the database migrations for the Laravel ACL package. This command creates the necessary tables in your database to support the ACL functionality.

```bash
php artisan migrate
```

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

### Install Laravel ACL with Composer

Source: https://github.com/yajra/laravel-acl-docs/blob/master/installation.md

Installs the latest version of the yajra/laravel-acl package using Composer. Ensure you have Composer installed and configured for your Laravel project.

```bash
composer require yajra/laravel-acl:"^13.0"
```

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

### Publish Laravel ACL Configuration

Source: https://github.com/yajra/laravel-acl-docs/blob/master/installation.md

Publishes the configuration file for the Laravel ACL package to your application's config directory. This allows for customization of ACL settings.

```bash
php artisan vendor:publish --tag=laravel-acl
```

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

### Register Laravel ACL Middleware

Source: https://github.com/yajra/laravel-acl-docs/blob/master/installation.md

Registers the role, permission, and canAtLeast middleware aliases within the `bootstrap/app.php` file for Laravel 13. This makes the middleware available for use in your application's routes and controllers.

```php
<?php

use Illuminate\Foundation\Application;
use Illuminate\Foundation\Configuration\Exceptions;
use Illuminate\Foundation\Configuration\Middleware;

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
    )
    ->withMiddleware(function (Middleware $middleware) {
        $middleware->alias([
            'role' => \Yajra\Acl\Middleware\RoleMiddleware::class,
            'permission' => \Yajra\Acl\Middleware\PermissionMiddleware::class,
            'canAtLeast' => \Yajra\Acl\Middleware\CanAtLeastMiddleware::class,
        ]);
    })
    ->withExceptions(function (Exceptions $exceptions) {
        //
    })->create();

```

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

### Define User Model with InteractsWithRole Trait

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

This snippet shows how to use the InteractsWithRole trait in a User model. Ensure the trait is imported correctly. This setup is fundamental for role management.

```php
use App\Models\User;
use Yajra\Acl\Traits\InteractsWithRole;

class User extends Model
{
    use InteractsWithRole;
}
```

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

### Grant Permissions to Role - PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

Provides examples of granting permissions to a role using different identifiers: model ID, Permission model instance, permission slug string, and enum. It also shows how to add custom pivot attributes and control timestamp updates.

```php
$role = Role::find(1);

// Grant by model ID
$role->grantPermission(1);

// Grant by Permission model
$permission = Permission::find(1);
$role->grantPermission($permission);

// Grant by slug string
$role->grantPermission('create-post');

// Grant with pivot attributes
$role->grantPermission('create-post', ['expires_at' => now()->addMonth()]);

// Grant from enum
enum PermissionEnum: string
{
    case CreatePost = 'create-post';
}

$role->grantPermission(PermissionEnum::CreatePost);
```

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

### Get All Role Permissions - PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

This code snippet illustrates how to retrieve all permission slugs assigned to a role using the `getPermissions()` method. It returns an array of strings, where each string is a permission slug.

```php
$role = Role::find(1);

$permissions = $role->getPermissions();
// ['users.create', 'users.view', 'users.delete']
```

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

### Get User Role Slugs with getRoleSlugs()

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

This function retrieves all role slugs currently assigned to a user. It returns an array containing the slugs of the roles.

```php
use App\Models\User;

$user = User::find(1);

$slugs = $user->getRoleSlugs();
// ['admin', 'editor', 'moderator']
```

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

### Define VitePress Frontmatter

Source: https://github.com/yajra/laravel-acl-docs/blob/master/AGENTS.md

Standard YAML frontmatter required at the top of every documentation file for SEO and page metadata. It must be the first content in the file.

```yaml
---
title: "Page Title"
description: "Brief description for SEO"
---
```

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

### Implement Heading Anchors

Source: https://github.com/yajra/laravel-acl-docs/blob/master/AGENTS.md

Required HTML anchor tags for H2 headings to ensure consistent internal navigation. These must be placed immediately before the heading text.

```html
<a name="usage"></a>
## Usage
```

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

### Using Enums with Authorization Methods

Source: https://github.com/yajra/laravel-acl-docs/blob/master/auth.md

Explains and demonstrates how to use both BackedEnum and UnitEnum types with the authorization methods (`hasRole`, `canAccess`, `canAtLeast`). The methods correctly interpret enum values or names.

```php
// BackedEnum - Uses the enum's value
enum RoleEnum: string
{
    case Admin = 'administrator';
    case User = 'registered';
}

// UnitEnum - Uses the enum's name
enum PermissionLevel
{
    case Read;
    case Write;
    case Admin;
}

$user = User::find(1);

// All valid usages:
$user->hasRole(RoleEnum::Admin);                 // valid
$user->hasRole(PermissionLevel::Admin);          // valid
$user->canAccess(PermissionLevel::Write);        // valid
$user->canAtLeast(PermissionLevel::Read);        // valid
```

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

### Define and Use PHP Enums for Permissions

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

Demonstrates how to implement BackedEnum and UnitEnum for permission definitions. Shows how these enums are passed into role-based permission methods like can, grantPermission, and revokePermission.

```php
enum PermissionEnum: string
{
    case CreatePost = 'create-post';
    case ViewPost = 'view-post';
}

enum PermissionLevel
{
    case Read;
    case Write;
    case Admin;
}

$role = Role::find(1);

$role->can(PermissionEnum::CreatePost);
$role->can(PermissionLevel::Admin);
$role->grantPermission(PermissionEnum::CreatePost);
$role->revokePermission(PermissionLevel::Write);
```

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

### Implement 'canAtLeast' Permission Middleware

Source: https://github.com/yajra/laravel-acl-docs/blob/master/middleware.md

The 'canAtLeast' middleware ensures a user possesses at least one of the provided permissions. Permissions are passed as a comma-separated string.

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

// User needs at least one of these permissions
Route::get('/users', function () {
    //
})->middleware('canAtLeast:users.view,users.create');
```

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

### Implement Permission-Based Route Middleware

Source: https://github.com/yajra/laravel-acl-docs/blob/master/middleware.md

Use the 'permission' middleware to verify specific user permissions. Supports single or multiple permissions separated by a pipe (|) for OR logic.

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

// Single permission check
Route::get('/users', function () {
    //
})->middleware('permission:users.view');

// Multiple permissions (OR logic - user needs ANY of these permissions)
Route::get('/users', function () {
    //
})->middleware('permission:users.view|users.create');
```

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

### Check Role Permissions (can, cannot, canAtLeast) - PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

Demonstrates how to check if a role has specific permissions using the `can()`, `cannot()`, and `canAtLeast()` methods. `can()` checks for all specified permissions (AND logic), `cannot()` checks for the absence of all specified permissions (AND logic), and `canAtLeast()` checks if at least one permission exists (OR logic).

```php
$role = Role::find(1);

// Single permission check
if ($role->can('users.create')) {
    // Role has this permission
}

// Array means ALL must match (AND logic)
if ($role->can(['users.create', 'users.view'])) {
    // Role has BOTH permissions
}

// Returns true if role does NOT have this permission
if ($role->cannot('users.delete')) {
    // Role lacks this permission
}

// Returns true only if role does NOT have ALL of these permissions
if ($role->cannot(['users.create', 'users.view'])) {
    // Role is missing at least one of these permissions
}

// Returns true if role has at least ONE of these permissions
if ($role->canAtLeast(['users.create', 'users.view'])) {
    // Role has at least one of these permissions
}
```

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

### Enum Support for Role Management in PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Demonstrates how the Laravel ACL package seamlessly integrates with PHP enums for role management. Both BackedEnum (using `->value`) and UnitEnum (using `->name`) are supported for methods like `hasRole`, `attachRole`, and `revokeRole`.

```php
<?php

// BackedEnum - Uses the enum's value
enum RoleEnum: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}

// UnitEnum - Uses the enum's name
enum PermissionLevel
{
    case Read;
    case Write;
    case Admin;
}

$user = User::find(1);

// All valid usages:
$user->hasRole(RoleEnum::Admin);           // valid
$user->hasRole(PermissionLevel::Admin);   // valid
$user->attachRole(RoleEnum::Editor);       // valid
$user->revokeRole(PermissionLevel::Write); // valid
?>
```

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

### Check Permissions with canAtLeast Method

Source: https://github.com/yajra/laravel-acl-docs/blob/master/auth.md

Shows how to use the `canAtLeast` method to determine if a user has at least one of the specified permissions, either directly or through their assigned roles. Supports single or multiple permission checks.

```php
// Single permission check
if ($user->canAtLeast('users.create')) {
    // User can create users
}

// Multiple permissions (OR logic)
if ($user->canAtLeast(['users.create', 'users.view'])) {
    // User has at least one of these permissions
}
```

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

### Enum Support for Permissions

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Demonstrates how to use BackedEnum and UnitEnum types with permission methods. The system automatically resolves values based on the enum type.

```php
enum PermissionEnum: string {
    case CreatePost = 'create-post';
    case ViewPost = 'view-post';
}

enum PermissionLevel {
    case Read;
    case Write;
    case Admin;
}

$user = User::find(1);
$user->grantPermission(PermissionEnum::CreatePost);
$user->grantPermission(PermissionLevel::Write);
$user->revokePermission(PermissionEnum::ViewPost);
```

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

### Apply Middleware to Route Groups

Source: https://github.com/yajra/laravel-acl-docs/blob/master/middleware.md

Group multiple routes under a single middleware check to simplify authorization logic for related endpoints.

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

// Role-based route group
Route::middleware(['auth', 'role:administrator'])->group(function () {
    Route::get('/admin', function () {
        //
    });
});

// Permission-based route group
Route::middleware(['auth', 'permission:users.view'])->prefix('users')->group(function () {
    Route::get('/', function () {
        //
    });
});
```

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

### Retrieve All User Permissions with getPermissions

Source: https://github.com/yajra/laravel-acl-docs/blob/master/auth.md

This snippet demonstrates the `getPermissions` method, which retrieves all permission slugs associated with the user, including those granted through their roles. It returns an array of permission slugs.

```php
$user = User::find(1);

$permissions = $user->getPermissions();
// ['users.create', 'users.view', 'posts.delete']
```

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

### Implement Role-Based Route Middleware

Source: https://github.com/yajra/laravel-acl-docs/blob/master/middleware.md

Use the 'role' middleware to restrict route access based on user roles. Supports single roles or multiple roles using a pipe (|) delimiter for OR logic.

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

// Single role check
Route::get('/admin', function () {
    //
})->middleware('role:administrator');

// Multiple roles (OR logic - user needs ANY of these roles)
Route::get('/users', function () {
    //
})->middleware('role:administrator|cashier');
```

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

### Check Permissions and Roles with canAccess Method

Source: https://github.com/yajra/laravel-acl-docs/blob/master/auth.md

Illustrates the `canAccess` method for checking if a user has a specific permission or role. This method is versatile, allowing checks for single or multiple permissions/roles with OR logic.

```php
// Check a single permission
if ($user->canAccess('users.create')) {
    // User can create users
}

// Check multiple (any match)
if ($user->canAccess(['users.create', 'users.view', 'administrator'])) {
    // User has at least one of these
}
```

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

### Check User Roles with hasRole Method

Source: https://github.com/yajra/laravel-acl-docs/blob/master/auth.md

Demonstrates how to use the `hasRole` method to verify if a user possesses specific roles. It supports checking a single role, multiple roles (using OR logic), and enums.

```php
// Single role check
if ($user->hasRole('administrator')) {
    // User is an administrator
}

// Multiple roles (OR logic - true if user has ANY of the roles)
if ($user->hasRole(['administrator', 'registered'])) {
    // User is an administrator OR registered
}

// Using enums
enum RoleEnum: string
{
    case Admin = 'administrator';
    case User = 'registered';
}

if ($user->hasRole(RoleEnum::Admin)) {
    // User is an admin
}
```

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

### Laravel ACL Method Signatures

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

A collection of method signatures for managing permissions, including checking status, granting access, revoking privileges, and syncing permission sets.

```php
can(string|array $permission): bool;
cannot(string|array $permission): bool;
canAtLeast(string|array $permission): bool;
getPermissions(): array;

grantPermission(mixed $permission, array $attributes = [], bool $touch = true): void;
grantPermissionBySlug(string|array $slug): void;
grantPermissionByResource(string|array $resource): void;

revokePermission(mixed $permission = null, bool $touch = true): int;
revokePermissionBySlug(string|array $slug, bool $touch = true): void;
revokePermissionByResource(string|array $resource, bool $touch = true): void;
revokeAllPermissions(): int;

syncPermissions(Collection|Model|array $ids, bool $detaching = true): array;
```

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

### Check Permissions with Built-in Directives

Source: https://github.com/yajra/laravel-acl-docs/blob/master/directives.md

Demonstrates the use of standard Laravel @can and @cannot directives to conditionally render content based on user permissions.

```php
@can('posts.update')
    <!-- The Current User Can Update The Post -->
@endcan

@cannot('posts.update')
    <!-- The Current User Can't Update The Post -->
@endcannot
```

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

### Check User Roles with hasRole()

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Demonstrates how to check if a user has a specific role or multiple roles using the `hasRole()` method. It supports checking against role slugs (strings), arrays of slugs, and enums. Returns true if the user possesses any of the specified roles when an array is provided.

```php
use App\Models\User;

$user = User::find(1);

// Single role check
if ($user->hasRole('admin')) {
    // User is an admin
}

// Multiple roles (OR logic - true if user has ANY of the roles)
if ($user->hasRole(['admin', 'editor'])) {
    // User is an admin OR editor
}

// Using enums
enum RoleEnum: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}

if ($user->hasRole(RoleEnum::Admin)) {
    // User is an admin
}
```

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

### Configure Models and Cache in Laravel ACL

Source: https://github.com/yajra/laravel-acl-docs/blob/master/general-settings.md

This configuration allows you to specify custom User, Role, and Permission models for the Laravel ACL package. It also enables or disables caching for permissions and defines the cache key. The configuration is managed in the `config/acl.php` file.

```php
return [
    /**
     * User class used for ACL.
     */
    'user' => App\Models\User::class,

    /**
     * Role class used for ACL.
     */
    'role' => Yajra\Acl\Models\Role::class,

    /**
     * Permission class used for ACL.
     */
    'permission' => Yajra\Acl\Models\Permission::class,

    /**
     * Cache config.
     */
    'cache' => [
        'enabled' => true,

        'key' => 'permissions.policies',
    ],
];
```

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

### User Role Management API

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Methods for checking, attaching, revoking, and syncing roles for users.

```APIDOC
## Checking Roles

### `hasRole($role)`

Check if the user has the given role.

**Parameters:**
- **$role** (string | array<string> | BackedEnum | UnitEnum) - Role slug(s) or enum to check.

> **Note**: Returns `true` if the user has **any** of the roles when using an array.

**Example:**
```php
$user = User::find(1);

if ($user->hasRole('admin')) {
    // User is an admin
}

if ($user->hasRole(['admin', 'editor'])) {
    // User is an admin OR editor
}
```

### `getRoleSlugs()`

Get all role slugs assigned to the user.

**Returns:** Array of role slugs.

**Example:**
```php
$user = User::find(1);
$slugs = $user->getRoleSlugs();
// ['admin', 'editor', 'moderator']
```

## Attaching Roles

### `attachRole($role, $attributes = [], $touch = true)`

Attach a role to the user.

**Parameters:**
- **$role** (mixed) - Role model instance, role slug (string), or enum.
- **$attributes** (array) - Pivot table attributes (e.g., `['expires_at' => now()->addMonth()]`). Defaults to `[]`.
- **$touch** (bool) - Whether to touch the model's timestamps. Defaults to `true`.

**Example:**
```php
$user = User::find(1);
$user->attachRole('admin', ['expires_at' => now()->addMonth()]);
```

### `attachRoleBySlug($slug)`

Attach a role using only the role slug (alias for `attachRole($slug)`).

**Parameters:**
- **$slug** (string) - Role slug to attach.

**Example:**
```php
$user = User::find(1);
$user->attachRoleBySlug('admin');
```

## Revoking Roles

### `revokeRole($role, $touch = true)`

Revoke a role from the user.

**Parameters:**
- **$role** (mixed) - Role model instance, role slug (string), or enum.
- **$touch** (bool) - Whether to touch the model's timestamps. Defaults to `true`.

> **Note**: Returns the number of roles detached.

**Example:**
```php
$user = User::find(1);
$detached = $user->revokeRole('admin');
```

### `revokeRoleBySlug($slug, $touch = true)`

Revoke a role using the role slug.

**Parameters:**
- **$slug** (string | array<string>) - Role slug(s) to revoke.
- **$touch** (bool) - Whether to touch the model's timestamps. Defaults to `true`.

**Example:**
```php
$user = User::find(1);
$detached = $user->revokeRoleBySlug(['admin', 'editor']);
```

### `revokeAllRoles()`

Revoke all roles from the user.

**Returns:** Number of roles detached.

**Example:**
```php
$user = User::find(1);
$detached = $user->revokeAllRoles();
```
```

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

### Grant Permissions by Slug - PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

This snippet demonstrates granting one or more permissions to a role using their string slugs. The `grantPermissionBySlug()` method accepts either a single slug or an array of slugs.

```php
$role = Role::find(1);

// Grant single permission by slug
$role->grantPermissionBySlug('create-post');

// Grant multiple permissions by slug
$role->grantPermissionBySlug(['create-post', 'view-post', 'edit-post']);
```

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

### Grant Permissions by Slug or Resource

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Bulk grant permissions based on specific slug strings or resource names associated with the application.

```php
$user = User::find(1);

// Grant single/multiple permissions by slug
$user->grantPermissionBySlug('create-post');
$user->grantPermissionBySlug(['create-post', 'view-post']);

// Grant all permissions for a resource
$user->grantPermissionByResource('Posts');
$user->grantPermissionByResource(['Users', 'Posts']);
```

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

### Sync User Roles in PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Synchronizes a user's roles by replacing existing roles with a new set. It supports syncing with role IDs, role models, and offers an option to detach roles not included in the new list. The method returns an array indicating attached, detached, and updated roles.

```php
<?php

$user = User::find(1);

// Sync with role IDs
$result = $user->syncRoles([1, 2, 3]);
// ['attached' => [1, 2, 3], 'detached' => [], 'updated' => []]

// Sync with role models
$roles = Role::whereIn('slug', ['admin', 'editor'])->get();
$result = $user->syncRoles($roles);

// Sync without detaching (keeps existing roles)
$result = $user->syncRoles([1, 2], detaching: false);
?>
```

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

### Sync permissions in Laravel ACL

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

Synchronizes a role's permissions by replacing current assignments with the provided list. Supports detaching existing permissions not present in the new list and accepts collections, models, or arrays of IDs.

```php
$role = Role::find(1);

// Sync with replacement (revokes any not in list)
$result = $role->syncPermissions([1, 2, 3]);

// Sync without detaching (keeps existing permissions)
$result = $role->syncPermissions([1, 2], detaching: false);

// Sync with Collection
$permissions = Permission::where('resource', 'Posts')->get();
$result = $role->syncPermissions($permissions);

// Sync with single Permission model
$permission = Permission::find(1);
$result = $role->syncPermissions($permission);
```

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

### Attach Role by Slug with attachRoleBySlug()

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

A convenience method that attaches a role to a user using only the role's slug. It serves as an alias for `attachRole($slug)`.

```php
use App\Models\User;

$user = User::find(1);
$user->attachRoleBySlug('admin');
```

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

### Sync Permissions

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Synchronizes a user's permissions with the provided list. It allows for optional detaching of existing permissions not present in the input array and returns a report of changes.

```php
$user = User::find(1);

// Sync single permission
$user->syncPermissions(1);

// Sync multiple permissions
$user->syncPermissions([1, 2, 3]);

// Sync without detaching existing permissions
$user->syncPermissions([1, 2], detaching: false);

// Get change details
$result = $user->syncPermissions([1, 2, 3]);
```

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

### Implement HasRole Trait in User Model

Source: https://github.com/yajra/laravel-acl-docs/blob/master/auth.md

This snippet shows how to integrate the HasRole trait into your User model. Ensure your User model extends Authenticatable and uses the HasRole trait to enable authorization methods.

```php
use Illuminate\Foundation\Auth\User as Authenticatable;
use Yajra\Acl\Traits\HasRole;

class User extends Authenticatable
{
    use HasRole;
}
```

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

### Implement HasRole trait in User model

Source: https://github.com/yajra/laravel-acl-docs/blob/master/usage.md

Integrates the HasRole trait into the Eloquent User model to enable basic role management functionality. This trait provides the necessary methods to link users with roles and permissions.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Yajra\Acl\Traits\HasRole;

class User extends Authenticatable
{
    use HasFactory;
    use Notifiable;
    use HasRole;

    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    protected $hidden = [
        'password',
        'remember_token',
    ];
}
```

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

### Implement HasRoleAndPermission trait in User model

Source: https://github.com/yajra/laravel-acl-docs/blob/master/usage.md

Integrates the HasRoleAndPermission trait to provide both role management and custom user-specific permission capabilities. This extends the functionality of the standard HasRole trait.

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Factories\HasFactory;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Notifications\Notifiable;
use Yajra\Acl\Traits\HasRoleAndPermission;

class User extends Authenticatable
{
    use HasFactory;
    use Notifiable;
    use HasRoleAndPermission;

    protected $fillable = [
        'name',
        'email',
        'password',
    ];

    protected $hidden = [
        'password',
        'remember_token',
    ];
}
```

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

### Attach Roles to User with attachRole()

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Allows attaching roles to a user. Roles can be specified as a model instance, a role slug (string), or an enum. It also supports adding custom attributes to the pivot table and controlling timestamp updates.

```php
use App\Models\User;
use App\Models\Role;

$user = User::find(1);

// Attach by role model
$role = Role::find(1);
$user->attachRole($role);

// Attach by slug
$user->attachRole('admin');

// Attach by enum
enum RoleEnum: string
{
    case Admin = 'admin';
}

$user->attachRole(RoleEnum::Admin);

// Attach with pivot attributes
$user->attachRole('admin', ['expires_at' => now()->addMonth()]);
```

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

### Define Role Model with InteractsWithPermission Trait

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

This snippet shows how to define a Role model that utilizes the InteractsWithPermission trait from the Yajra ACL package. This trait provides methods for managing permissions.

```php
use App\Models\Role;
use Yajra\Acl\Traits\InteractsWithPermission;

class Role extends Model
{
    use InteractsWithPermission;
}
```

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

### User Permissions API

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

This section covers the API for managing direct user permissions using the HasRoleAndPermission trait. It includes methods for granting, revoking, and retrieving user permissions.

```APIDOC
## User Permissions Management

### Description
This API provides methods to manage direct permissions for a user, independent of roles. It allows granting, revoking, and checking permissions.

### Methods

#### `getPermissions()`

##### Description
Retrieves an array of all permission slugs assigned directly to the user, as well as those inherited from roles.

##### Method
`GET`

##### Endpoint
`/users/{user_id}/permissions` (Conceptual - this is a model method)

##### Response
*   **permissions** (array) - An array of permission slugs.

##### Response Example
```json
{
  "permissions": [
    "users.create",
    "users.view",
    "posts.delete"
  ]
}
```

#### `grantPermission($permission, $attributes = [], $touch = true)`

##### Description
Grants one or more permissions to the user. Permissions can be specified by ID, slug, model instance, or enum.

##### Method
`POST`

##### Endpoint
`/users/{user_id}/permissions` (Conceptual - this is a model method)

##### Parameters
*   **permission** (mixed) - Required - Permission model instance, ID, slug string, or enum.
*   **attributes** (array) - Optional - Pivot table attributes (e.g., `{"expires_at": "2025-12-31"}`).
*   **touch** (bool) - Optional - Whether to touch the model's timestamps. Defaults to `true`.

##### Request Example
```json
{
  "permission": "create-post",
  "attributes": {
    "expires_at": "2025-12-31"
  }
}
```

#### `grantPermissionBySlug($slug)`

##### Description
Grants permissions to the user based on their slug(s).

##### Method
`POST`

##### Endpoint
`/users/{user_id}/permissions/by-slug` (Conceptual - this is a model method)

##### Parameters
*   **slug** (string | array<string>) - Required - Permission slug(s) to grant.

##### Request Example
```json
{
  "slug": ["create-post", "view-post"]
}
```

#### `grantPermissionByResource($resource)`

##### Description
Grants all permissions associated with the specified resource name(s) to the user.

##### Method
`POST`

##### Endpoint
`/users/{user_id}/permissions/by-resource` (Conceptual - this is a model method)

##### Parameters
*   **resource** (string | array<string>) - Required - Resource name(s) to grant permissions for.

##### Request Example
```json
{
  "resource": "Posts"
}
```

#### `revokePermission($permission = null, $touch = true)`

##### Description
Revokes one or more permissions from the user. Passing `null` revokes all permissions.

##### Method
`DELETE`

##### Endpoint
`/users/{user_id}/permissions` (Conceptual - this is a model method)

##### Parameters
*   **permission** (mixed) - Optional - Permission model, ID, slug, enum, or array of these. If `null`, all permissions are revoked.
*   **touch** (bool) - Optional - Whether to touch the model's timestamps. Defaults to `true`.

##### Request Example
```json
{
  "permission": 1
}
```

##### Response
*   **detached_count** (integer) - The number of permissions detached.

##### Response Example
```json
{
  "detached_count": 1
}
```
```

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

### Enable HasRoleAndPermission Trait

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Integrate the HasRoleAndPermission trait into the User model to enable direct permission assignment capabilities.

```php
use Illuminate\Foundation\Auth\User as Authenticatable;
use Yajra\Acl\Traits\HasRoleAndPermission;

class User extends Authenticatable
{
    use HasRoleAndPermission;
}
```

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

### Grant permissions by resource in Laravel ACL

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

Grants all permissions associated with specific resource names to a role. Accepts either a single string or an array of resource names.

```php
$role = Role::find(1);

// Grant all permissions for a single resource
$role->grantPermissionByResource('Posts');

// Grant all permissions for multiple resources
$role->grantPermissionByResource(['Users', 'Posts']);
```

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

### Filter Models by Roles in PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Applies query scopes to filter Eloquent models based on their assigned roles. Supports filtering by role IDs, slugs, enums (BackedEnum and UnitEnum), and role model instances. It also allows for mixed filtering criteria within a single query.

```php
<?php

// Filter by role ID
$users = User::havingRoles([1, 2])->get();

// Filter by role slugs
$users = User::havingRoles(['admin', 'editor'])->get();

// Filter by enums
enum RoleEnum: string
{
    case Admin = 'admin';
    case Editor = 'editor';
}

$users = User::havingRoles([RoleEnum::Admin, RoleEnum::Editor])->get();

// Filter by role models
$roles = Role::where('slug', 'admin')->get();
$users = User::havingRoles($roles)->get();

// Mixed filter
$users = User::havingRoles([
    1,                          // Role ID
    'admin',                   // Role slug
    RoleEnum::Editor,          // Enum
    Role::find(2),             // Role model
])->get();
?>
```

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

### Check Multiple Permissions with @canAtLeast

Source: https://github.com/yajra/laravel-acl-docs/blob/master/directives.md

Uses the @canAtLeast directive to check if a user possesses at least one of the provided permissions, supporting both strings and arrays.

```php
@canAtLeast(['posts.update', 'posts.view'])
    <!-- The Current User Can Update or View The Post -->
@endCanAtLeast
```

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

### Grant Permissions to User

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Assign permissions to a user using various formats including IDs, slugs, models, or enums. Supports optional pivot attributes and timestamp touching.

```php
$user = User::find(1);

// Grant by permission ID
$user->grantPermission(1);

// Grant by slug
$user->grantPermission('create-post');

// Grant with pivot attributes
$user->grantPermission('create-post', ['expires_at' => '2025-12-31']);

// Grant from Permission model
$permission = Permission::find(1);
$user->grantPermission($permission);

// Grant multiple permissions at once
$permissions = Permission::all();
$user->grantPermission($permissions);

// Grant from enum
enum PermissionEnum: string
{
    case CreatePost = 'create-post';
    case ViewPost = 'view-post';
}

$user->grantPermission(PermissionEnum::CreatePost);
```

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

### Check User Roles with @role

Source: https://github.com/yajra/laravel-acl-docs/blob/master/directives.md

Demonstrates the @role directive to restrict content based on user roles. It supports checking for a single role or multiple roles using an array (OR logic).

```php
// Single role check
@role('administrator')
    <!-- The Current User is an Administrator -->
@endRole

// Multiple roles (OR logic)
@role(['administrator', 'moderator'])
    <!-- User is admin OR moderator -->
@endRole
```

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

### Filter Models by Role Slugs in PHP

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Filters Eloquent models specifically by an array of role slugs. This scope is useful when you need to retrieve users who possess one or more roles identified by their string slugs.

```php
<?php

$users = User::havingRolesBySlugs(['admin', 'editor'])->get();
?>
```

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

### Revoke Permissions by Resource

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Removes all permissions associated with a specific resource or set of resources. It finds all relevant permissions linked to the resource name and detaches them from the user.

```php
$user = User::find(1);

// Revoke all permissions for a single resource
$user->revokePermissionByResource('Posts');

// Revoke permissions for multiple resources
$user->revokePermissionByResource(['Users', 'Posts']);
```

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

### Revoke User Permissions

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Remove specific permissions from a user or clear all permissions by passing null. Returns the count of detached permissions.

```php
$user = User::find(1);

// Revoke by ID, slug, or enum
$detached = $user->revokePermission(1);
$detached = $user->revokePermission('create-post');
$detached = $user->revokePermission(PermissionEnum::CreatePost);

// Revoke all permissions
$detached = $user->revokePermission();
```

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

### Revoke Roles from User with revokeRole()

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Detaches roles from a user. Roles can be specified as a model instance, a role slug (string), or an enum. The method returns the count of detached roles and allows controlling timestamp updates.

```php
use App\Models\User;
use App\Models\Role;

$user = User::find(1);

// Revoke by role model
$role = Role::find(1);
$detached = $user->revokeRole($role);

// Revoke by slug
$detached = $user->revokeRole('admin');

// Revoke by enum
enum RoleEnum: string
{
    case Admin = 'admin';
}

$detached = $user->revokeRole(RoleEnum::Admin);
```

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

### Revoke All Roles with revokeAllRoles()

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Removes all assigned roles from a user. This is a comprehensive method for clearing all role associations for a given user. It returns the total number of roles that were detached.

```php
use App\Models\User;

$user = User::find(1);

$detached = $user->revokeAllRoles();
```

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

### Revoke Permissions by Slug

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Revokes specific permissions from a user by providing their slug or an array of slugs. This method identifies matching permissions and detaches them from the user model.

```php
$user = User::find(1);

// Revoke single permission by slug
$user->revokePermissionBySlug('create-post');

// Revoke multiple permissions by slug
$user->revokePermissionBySlug(['create-post', 'update-post']);
```

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

### Revoke permissions in Laravel ACL

Source: https://github.com/yajra/laravel-acl-docs/blob/master/role.md

Provides multiple methods to remove permissions from a role, including by model, slug, resource, or clearing all permissions. Most methods support an optional touch parameter to update timestamps.

```php
$role = Role::find(1);

// Revoke by model ID
$detached = $role->revokePermission(1);

// Revoke by Permission model
$permission = Permission::find(1);
$detached = $role->revokePermission($permission);

// Revoke by slug
$detached = $role->revokePermission('create-post');

// Revoke multiple
$role->revokePermission([1, 2]);
$role->revokePermission(['create-post', 'view-post']);

// Revoke all
$detached = $role->revokePermission();

// Revoke by slug specifically
$role->revokePermissionBySlug('create-post');

// Revoke by resource
$role->revokePermissionByResource('Posts');

// Revoke all permissions
$detached = $role->revokeAllPermissions();
```

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

### Revoke Roles by Slug with revokeRoleBySlug()

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission.md

Detaches one or more roles from a user using their slugs. This method accepts a single slug string or an array of slugs. It also allows controlling timestamp updates and returns the count of detached roles.

```php
use App\Models\User;

$user = User::find(1);

// Revoke a single role
$detached = $user->revokeRoleBySlug('admin');

// Revoke multiple roles at once
$detached = $user->revokeRoleBySlug(['admin', 'editor']);
```

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

### Revoke All Direct Permissions

Source: https://github.com/yajra/laravel-acl-docs/blob/master/permission-user.md

Removes every direct permission assigned to a user. Note that this does not affect permissions inherited through roles.

```php
$user = User::find(1);

$detached = $user->revokeAllPermissions();
```
Tokens:
Raw