Ladder

https://github.com/eneadm/ladder
Admin
Ladder is a Laravel package for role-based permissions: roles and their permissions are defined in...
Tokens:25,414
Snippets:184
Trust Score:7.2
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Run Ladder Install and Migrate Commands

Source: https://github.com/eneadm/ladder

Publishes and registers LadderServiceProvider, then runs the package's user_role migration.

```bash
php artisan ladder:install   # publishes app/Providers/LadderServiceProvider.php and registers it
```

```bash
php artisan migrate          # runs the package's user_role migration
```

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

### Usage command and output

Source: https://github.com/eneadm/ladder

Command to run the installer and the expected success message printed to the console.

```bash
php artisan ladder:install
# Ladder scaffolding installed successfully.
```

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

### Command signature and description

Source: https://github.com/eneadm/ladder

Defines the artisan command name and description for ladder:install. No arguments or options are accepted.

```php
protected $signature = 'ladder:install';

protected $description = 'Create the Ladder scaffolding.';
```

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

### Example output table from CommandTest.php

Source: https://github.com/eneadm/ladder

Example output shape asserted by the package test, showing a role × permission matrix with ✔/✖ cells.

```text
┌──────────┬───────┬────────┐
│          │ admin │ editor │
├──────────┼───────┼────────┤
│ create   │ ✔     │ ✔      │
│ delete   │ ✔     │ ✖      │
│ read     │ ✔     │ ✔      │
│ update   │ ✔     │ ✔      │
└──────────┴───────┴────────┘
```

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

### Usage examples for ladder:show

Source: https://github.com/eneadm/ladder

Shows how to invoke the command with different style options: default, borderless, compact, and box.

```bash
php artisan ladder:show
php artisan ladder:show default
php artisan ladder:show borderless
php artisan ladder:show compact
php artisan ladder:show box
```

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

### Basic usage of permissions method

Source: https://github.com/eneadm/ladder

Example showing how to call permissions() to get a collection of all permissions across the user's roles, e.g. ['read', 'create', 'update', 'delete'].

```php
$permissions = $user->permissions();
// Illuminate\Support\Collection, e.g. ['read', 'create', 'update', 'delete']
```

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

### Install Ladder via Composer

Source: https://github.com/eneadm/ladder/blob/main/README.md

Requires Laravel 12 and above. Run this command to install the package.

```bash
composer require eneadm/ladder
```

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

### Role::description() basic example

Source: https://github.com/eneadm/ladder

Creates a role with Ladder::role() and chains description(). The comment shows the resulting description property.

```php
use Ladder\Ladder;

$role = Ladder::role('admin', 'Administrator', ['post:read'])
    ->description('Full access to posts.');
// $role->description === 'Full access to posts.'
```

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

### Ladder::permissions()

Source: https://github.com/eneadm/ladder

Replaces the entire permission list with the provided array, without merging, deduplication, or sorting.

```APIDOC
## Ladder::permissions()

### Description
Replaces the entire permission list with the provided array, without merging, deduplication, or sorting.

### Method
Static method call

### Endpoint
`Ladder::permissions($permissions)`

### Parameters
#### Parameters
- **$permissions** (array) - Required - Wholesale replacement of `Ladder::$permissions` (no merge/dedupe/sort)

### Response
#### Success Response
- No return value specified
```

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

### Ladder::role()

Source: https://github.com/eneadm/ladder

Registers a role with a key, display name, and permission list. Later registrations with the same key overwrite earlier definitions.

```APIDOC
## Ladder::role()

### Description
Registers a role with a key, display name, and permission list. Later registrations with the same key overwrite earlier definitions.

### Method
Static method call

### Endpoint
`Ladder::role($key, $name, $permissions)`

### Parameters
#### Parameters
- **$key** (string) - Required - Role slug; later registrations with the same key overwrite the earlier definition
- **$name** (string) - Required - Display name (translated via `__()` on JSON serialization)
- **$permissions** (array) - Required - Permission strings; wildcards `*`, `*:create`, `*:update` supported

### Response
#### Success Response
- No return value specified

### Request Example
```php
Ladder::role('admin', 'Administrator', [
    'create', 'read', 'update', 'delete',
])->description('Administrator users can perform any action.');

Ladder::role('editor', 'Editor', [
    'read', 'create', 'update',
])->description('Editor users have the ability to read, create, and update.');
```
```

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

### Role::description() chainable example

Source: https://github.com/eneadm/ladder

Shows chaining description() on an existing Role instance. Later calls win; each returns $this.

```php
use Ladder\Role;

$role = (new Role('editor', 'Editor', ['post:read']))
    ->description('Can read posts.')
    ->description('Can read and write posts.'); // later call wins; returns $this each time
```

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

### configureCommands method signature

Source: https://github.com/eneadm/ladder

Registers Console\InstallCommand and Console\Show if running in console, making ladder:install and ladder:show available. Returns early if not running in console. No parameters, returns void, throws none.

```php
public function configureCommands(): void
```

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

### installServiceProviderAfter() method signature

Source: https://github.com/eneadm/ladder

Protected method signature for inserting a service provider after another in config/app.php. Parameters expect provider class names without namespace prefix.

```php
protected function installServiceProviderAfter($after, $name): void
```

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

### handle() method signature

Source: https://github.com/eneadm/ladder

Public method signature for the command's handle method. Returns a boolean, always true on success.

```php
public function handle(): bool
```

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

### Create LadderServiceProvider with artisan ladder:install

Source: https://github.com/eneadm/ladder/blob/main/README.md

Run this command after installation to create a new LadderServiceProvider for managing roles and permissions.

```bash
php artisan ladder:install
```

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

### rolePermissions basic example

Source: https://github.com/eneadm/ladder

Collects permissions for a single role key. Returns an array of permission strings, deduplicated but not sorted.

```php
$permissions = $user->rolePermissions('admin');
// e.g. ['post:read', 'post:create']
```

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

### Role::jsonSerialize() basic serialization example

Source: https://github.com/eneadm/ladder

Creates a role with description, serializes it, and shows json_encode() equivalence. The comment shows the expected serialized array.

```php
use Ladder\Ladder;

$role = Ladder::role('admin', 'Administrator', ['read', 'create'])
    ->description('Some admin description');

$serialized = $role->jsonSerialize();
// ['key' => 'admin', 'name' => 'Administrator', 'description' => 'Some admin description', 'permissions' => ['read', 'create']]

$json = json_encode($role); // JsonSerializable makes this equivalent to json_encode($role->jsonSerialize())
```

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

### App-level provider stub published by ladder:install

Source: https://github.com/eneadm/ladder

This stub is copied to app/Providers/ by the install command. It defines configurePermissions() calling Ladder::role(...) to register roles like 'admin' and 'editor' with descriptions.

```php
namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Ladder\Ladder;

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

    public function boot(): void
    {
        $this->configurePermissions();
    }

    protected function configurePermissions(): void
    {
        Ladder::role('admin', 'Administrator', [
            'create', 'read', 'update', 'delete',
        ])->description('Administrator users can perform any action.');

        Ladder::role('editor', 'Editor', [
            'read', 'create', 'update',
        ])->description('Editor users have the ability to read, create, and update.');
    }
}
```

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

### Register roles with Ladder::role()

Source: https://github.com/eneadm/ladder

Configure application roles in LadderServiceProvider using the Ladder::role() API. Later registrations with the same key overwrite earlier definitions. The global permission list is cumulative, deduplicated, and sorted across all role() calls.

```php
Ladder::role('admin', 'Administrator', [
    'create', 'read', 'update', 'delete',
])->description('Administrator users can perform any action.');

Ladder::role('editor', 'Editor', [
    'read', 'create', 'update',
])->description('Editor users have the ability to read, create, and update.');
```

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

### Define roles with Ladder::role in LadderServiceProvider

Source: https://github.com/eneadm/ladder/blob/main/README.md

Define roles with slug, name, permissions, and description using Ladder::role. Example shows admin and editor roles for a blog app.

```php
Ladder::role('admin', 'Administrator', [
    'post:read',
    'post:create',
    'post:update',
    'post:delete',
])->description('Administrator users can perform any action.');

Ladder::role('editor', 'Editor', [
    'post:read',
    'post:create',
    'post:update',
])->description('Editor users have the ability to read, create, and update posts.');
```

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

### Wildcard and multi-permission hasRolePermission examples

Source: https://github.com/eneadm/ladder

Demonstrates wildcard permission matching and multi-permission checks. Role 'content-manager' has ['*:create', '*:update', 'post:read']; 'user:create' returns true via '*:create', 'post:delete' returns false. Multiple permissions return true if any matches.

```php
// Role 'content-manager' has ['*:create', '*:update', 'post:read']:
$can = $user->hasRolePermission('content-manager', 'user:create'); // true ('*:create')
$can = $user->hasRolePermission('content-manager', 'post:delete'); // false

// Multiple requested permissions — true if ANY matches:
$can = $user->hasRolePermission('admin', ['post:read', 'post:delete']);
```

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

### Using permissions as a capability source

Source: https://github.com/eneadm/ladder

Example converting the permissions collection to an array and checking if a specific permission exists using in_array with strict comparison.

```php
$permissions = $user->permissions()->toArray();

if (in_array('post:update', $permissions, true)) {
    // ...
}
```

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

### Read roles via roles() relationship

Source: https://github.com/eneadm/ladder

Example showing how to read roles by accessing the roles property, which returns an Eloquent Collection of Ladder\Models\UserRole instances.

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

$user->roles; // Illuminate\Database\Eloquent\Collection of Ladder\Models\UserRole
```

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

### Basic hasRolePermission example

Source: https://github.com/eneadm/ladder

Checks if the user with role 'admin' has permission 'post:update'. Returns true if any requested permission is granted by the given roles.

```php
$can = $user->hasRolePermission('admin', 'post:update');
```

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

### Define roles with wildcard permissions

Source: https://github.com/eneadm/ladder/blob/main/README.md

Define roles using wildcard permissions: '*' grants all permissions, '*:create' grants all create permissions, '*:update' grants all update permissions. Example shows super-admin and content-manager roles.

```php
Ladder::role('super-admin', 'Super Administrator', [
    '*', // Full access to everything
])->description('Super Administrator users can perform any action.');

Ladder::role('content-manager', 'Content Manager', [
    '*:create', // Can create any resource
    '*:update', // Can update any resource
    'post:read',
])->description('Content Manager users can create and update any content.');
```

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

### filterRoles basic example

Source: https://github.com/eneadm/ladder

Filters the user's pivot records to those matching the given role keys. Returns a Collection of UserRole pivot records, empty when there are no matches.

```php
$matched = $user->filterRoles('admin');      // Collection of UserRole pivot records
$matched = $user->filterRoles(['admin', 'editor']);
$matched = $user->filterRoles($user->roles); // Collection of UserRole records
```

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

### Assign role to user using roles relationship

Source: https://github.com/eneadm/ladder/blob/main/README.md

Assign roles to a user using the roles relationship provided by the HasRoles trait. Example uses updateOrCreate with the role slug.

```php
use App\Models\User;

$user = User::find(1);

$user->roles()->updateOrCreate(['role' => 'admin']);
```

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

### boot method signature

Source: https://github.com/eneadm/ladder

Public method invoked by the framework on boot. Calls configurePublishing() then configureCommands(). No parameters, returns void, throws none.

```php
public function boot(): void
```

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

### handle method signature (src/Console/Show.php:80)

Source: https://github.com/eneadm/ladder

Public method signature for the command's handle method, which takes no parameters.

```php
public function handle()
```

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

### Command signature and description (src/Console/Show.php:12-15)

Source: https://github.com/eneadm/ladder

Defines the artisan command signature with an optional style argument (default|borderless|compact|box) and a description.

```php
protected $signature = 'ladder:show
        {style=default : The display style (default|borderless|compact|box)}';

protected $description = 'Show a table of roles and permissions';
```

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

### configurePublishing method signature

Source: https://github.com/eneadm/ladder

Loads the package migration via loadMigrationsFrom() to create the user_role table on php artisan migrate. No parameters, returns void, throws none.

```php
public function configurePublishing(): void
```

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

### Display roles and permissions table with ladder:show

Source: https://github.com/eneadm/ladder/blob/main/README.md

Run the ladder:show command to display a visual table of all roles and their permissions with ✔ and ✖ indicators.

```bash
php artisan ladder:show
```

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

### Role registration via Ladder::role() with description

Source: https://github.com/eneadm/ladder

Normal registration path using Ladder::role() and chaining description(). This is equivalent to direct construction but also sets the description, avoiding the uninitialized property error during serialization.

```php
use Ladder\Ladder;

$role = Ladder::role('admin', 'Administrator', ['post:read'])
    ->description('Administrator users can perform any action.');
```

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

### Creating role assignments with updateOrCreate and create

Source: https://github.com/eneadm/ladder

Shows how to assign roles to a user via the roles() relation. updateOrCreate updates an existing role or creates it; create adds a new role.

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

$user->roles()->updateOrCreate(['role' => 'admin']);
$user->roles()->create(['role' => 'editor']);
```

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

### ladder:show command table styles

Source: https://github.com/eneadm/ladder/blob/main/README.md

The ladder:show command supports different table styles: default, borderless, compact, and box.

```bash
php artisan ladder:show default
php artisan ladder:show borderless
php artisan ladder:show compact
php artisan ladder:show box
```

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

### Run migrations to create user_role table

Source: https://github.com/eneadm/ladder/blob/main/README.md

Execute the migration command to create the single pivot user_role table for assigning roles to users.

```bash
php artisan migrate
```

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

### Direct Role construction with new Role()

Source: https://github.com/eneadm/ladder

Creates a Role instance directly using the public constructor. Note that $description is uninitialized until description() is called, so serializing this instance would raise an Error.

```php
use Ladder\Role;

$role = new Role('admin', 'Administrator', ['post:read', 'post:create']);
```

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

### role: Fluent Return and Cumulative Permissions

Source: https://github.com/eneadm/ladder

Shows that role() returns a Role instance and that the global permission list accumulates across registrations, staying deduplicated and alphabetically sorted.

```php
use Ladder\Ladder;

$role = Ladder::role('editor', 'Editor', ['post:read', 'post:create']);

// Global permission list accumulates across registrations and stays sorted:
Ladder::role('viewer', 'Viewer', ['post:read']);

// Ladder::$permissions === ['post:create', 'post:read']
// Ladder::findRole('viewer')->name === 'Viewer'
```

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

### Ladder static registry state shapes

Source: https://github.com/eneadm/ladder

Declares the static properties `$roles` and `$permissions` on the `Ladder` class. `$roles` maps role keys to `Role` instances; `$permissions` is a flat, unique, sorted list of permission strings. `Ladder::permissions()` replaces `$permissions` wholesale without normalization.

```php
public static array $roles = [];        // array<string, Role>  — keyed by role key
public static array $permissions = [];  // array<int, string>   — flat, unique, sorted
```

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

### Role::jsonSerialize() return shape

Source: https://github.com/eneadm/ladder

Returns the JSON-serialized shape of a `Role` instance. The `description` key is only set after calling `Role::description()`; serializing before that raises a PHP `Error` due to an uninitialized typed property.

```php
[
    'key'         => string,  // $this->key
    'name'        => string,  // __($this->name)          — Laravel __() translated
    'description' => string,  // __($this->description)   — Laravel __() translated
    'permissions' => array,   // $this->permissions       — as provided at construction
]
```

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

### role: Basic Registration

Source: https://github.com/eneadm/ladder

Registers an 'admin' role with a list of permissions and chains ->description(). The method returns the new Role instance for fluent calls.

```php
use Ladder\Ladder;

Ladder::role('admin', 'Administrator', [
    'post:read',
    'post:create',
    'post:update',
    'post:delete',
])->description('Administrator users can perform any action.');
```

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

### role

Source: https://github.com/eneadm/ladder

Registers a new role with a key, name, and permissions. The method returns the newly created Role instance for fluent chaining.

```APIDOC
## role

### Description
Registers a new role with a key, name, and permissions. The method returns the newly created Role instance for fluent chaining.

### Method
`role`

### Signature
```php
public static function role(string $key, string $name, array $permissions)
```

### Parameters
- `$key` (string) - Required - Unique role key (slug), e.g. `'admin'`. Stored in `static::$roles[$key]`; re-registering the same key overwrites the previous definition.
- `$name` (string) - Required - Human-readable role name, e.g. `'Administrator'`. Passed through the Laravel `__()` translation helper when JSON-serialized.
- `$permissions` (array) - Required - List of permission strings granted to the role, e.g. `['post:read', 'post:create']`. Wildcards `*`, `*:create`, `*:update` are permitted.

### Return Type
No return type is declared in the source; the method returns the newly created `Role` instance (the result of `tap(new Role(...))`). The return value can be used fluently, e.g. `Ladder::role(...)->description(...)`.

### Behavior
1. Merges `$permissions` into `static::$permissions` via `array_merge`, then `->unique()->sort()->values()->all()` — so the global permission list is deduplicated and alphabetically sorted, and is **cumulative** across all `role()` calls.
2. Creates `new Role($key, $name, $permissions)` and registers it at `static::$roles[$key]`.

### Throws
None (PHP-level `TypeError` if arguments violate the declared types).

### Request Example
```php
use Ladder\Ladder;

Ladder::role('admin', 'Administrator', [
    'post:read',
    'post:create',
    'post:update',
    'post:delete',
])->description('Administrator users can perform any action.');
```

### Response Example
```php
use Ladder\Ladder;

$role = Ladder::role('editor', 'Editor', ['post:read', 'post:create']);

// Global permission list accumulates across registrations and stays sorted:
Ladder::role('viewer', 'Viewer', ['post:read']);

// Ladder::$permissions === ['post:create', 'post:read']
// Ladder::findRole('viewer')->name === 'Viewer'
```
```

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

### Role::description() signature

Source: https://github.com/eneadm/ladder

Exact signature of the description() method from src/Role.php:21. Returns static for chaining.

```php
public function description(string $description): static
```

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

### description(string $description): static

Source: https://github.com/eneadm/ladder

Sets the description for a Role instance. Returns $this to allow method chaining. The description is translated with Laravel's __() helper during JSON serialization.

```APIDOC
## `description`

### Description
Sets the description text for a Role instance. Returns the same instance ($this) to support fluent chaining. The description is passed through Laravel's `__()` translator at JSON-serialization time.

### Method
`description`

### Signature
```php
public function description(string $description): static
```

### Parameters
- `$description` (string) - Required - Description text; translated with `__()` at JSON-serialization time.

### Return Type
`static` — `$this`, so the call can be chained (fluent interface).

### Throws
None.

### Request Example
```php
use Ladder\Ladder;

$role = Ladder::role('admin', 'Administrator', ['post:read'])
    ->description('Full access to posts.');
// $role->description === 'Full access to posts.'
```

```php
use Ladder\Role;

$role = (new Role('editor', 'Editor', ['post:read']))
    ->description('Can read posts.')
    ->description('Can read and write posts.'); // later call wins; returns $this each time
```
```

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

### Role constructor signature

Source: https://github.com/eneadm/ladder

Exact signature of the public constructor. Assigns $key, $name, and $permissions but does not assign $description, which remains uninitialized until description() is called.

```php
public function __construct(string $key, string $name, array $permissions)
```

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

### permissions

Source: https://github.com/eneadm/ladder

Replaces the entire permission list with a new set of permissions. This method does not merge or deduplicate.

```APIDOC
## permissions

### Description
Replaces the entire permission list with a new set of permissions. This method does not merge or deduplicate.

### Method
`permissions`

### Signature
```php
public static function permissions(array $permissions): static
```

### Parameters
- `$permissions` (array) - Required - Complete replacement list of permission strings. Unlike `role()`, this **replaces** `static::$permissions` wholesale — no merge, no deduplication, no sorting.

### Return Type
`static` - a **new** `Ladder` instance (`new static`). The instance itself carries no state (all state is static); the return value is not meaningful beyond the static write performed by the call.

### Throws
None.

### Request Example
```php
use Ladder\Ladder;

Ladder::permissions(['post:read', 'post:update']);
// Ladder::$permissions === ['post:read', 'post:update']

Ladder::permissions(['post:read']);
// Ladder::$permissions === ['post:read']  (previous entries dropped)
```
```

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

### Ladder::permissions()

Source: https://github.com/eneadm/ladder

Replaces the static $permissions property with a flat, deduplicated, alphabetically sorted list of all permissions declared across all role() calls.

```APIDOC
## Ladder::permissions()

### Description
Replaces the static $permissions property with a flat, deduplicated, alphabetically sorted list of all permissions declared across all role() calls.

### Method
Static method call

### Endpoint
`Ladder::permissions()`

### Parameters
None

### Response
#### Success Response
- **void** - No return value.

```

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

### findRole: Handling Unregistered Role

Source: https://github.com/eneadm/ladder

Shows that findRole() returns null for an unregistered key like 'moderator', allowing graceful fallback. No exception is thrown.

```php
use Ladder\Ladder;

$role = Ladder::findRole('moderator'); // not registered

if ($role === null) {
    // No role definition exists for 'moderator' — fall back gracefully.
    return;
}
```

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

### Multiple permissions and wildcard behavior with hasPermission

Source: https://github.com/eneadm/ladder

Shows checking multiple permissions with an array and explains wildcard behavior: with role permission '*' any permission returns true; with '*:create' only matching create permissions return true.

```php
if ($user->hasPermission(['post:read', 'post:create'])) {
    // User can read OR create posts.
}

// With role permission '*' → hasPermission('anything') === true
// With role permission '*:create' → hasPermission('post:create') === true, hasPermission('post:read') === false
```

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

### permissions: Replace Permission List

Source: https://github.com/eneadm/ladder

Replaces the entire static permission list wholesale, dropping previous entries. Unlike role(), no merge, deduplication, or sorting is performed.

```php
use Ladder\Ladder;

Ladder::permissions(['post:read', 'post:update']);
// Ladder::$permissions === ['post:read', 'post:update']

Ladder::permissions(['post:read']);
// Ladder::$permissions === ['post:read']  (previous entries dropped)
```

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

### Role::__construct

Source: https://github.com/eneadm/ladder

Creates a new Role value object with a key, display name, and permission list. The constructor is public and can be used directly, though roles are typically created via Ladder::role().

```APIDOC
## Role::__construct

### Description
Creates a new Role value object with a key, display name, and permission list. The constructor is public and can be used directly, though roles are typically created via Ladder::role().

### Method
Constructor

### Signature
```php
public function __construct(string $key, string $name, array $permissions)
```

### Parameters
- **$key** (string) - Required - Role key (slug)
- **$name** (string) - Required - Display name
- **$permissions** (array) - Required - Permission strings granted to the role

### Behavior
Assigns $this->key, $this->name, $this->permissions. Does not assign $this->description.

### Throws
None.

### Request Example
```php
use Ladder\Role;

$role = new Role('admin', 'Administrator', ['post:read', 'post:create']);
```
```

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

### Role::jsonSerialize() missing description error case

Source: https://github.com/eneadm/ladder

Shows the error thrown when jsonSerialize() is called before description() is set. The catch block sets a fallback description and retries safely.

```php
use Ladder\Ladder;

$role = Ladder::role('admin', 'Administrator', ['read']);
// $role->description was never set:

try {
    $role->jsonSerialize();
} catch (\Error $e) {
    // "Typed property Ladder\Role::$description must not be accessed before initialization"
    $role->description('Fallback description');
    $serialized = $role->jsonSerialize(); // now safe
}
```

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

### hasPermissions: Check Registry Non-Empty

Source: https://github.com/eneadm/ladder

Checks whether at least one permission has been registered via role() or permissions(). Returns true when the global permission list is non-empty.

```php
use Ladder\Ladder;

if (Ladder::hasPermissions()) {
    // Some role has declared permissions; the registry is non-empty.
}
```

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

### findRole: Basic Lookup

Source: https://github.com/eneadm/ladder

Registers a role with Ladder::role() and retrieves it via Ladder::findRole('admin'). The returned Role instance has key 'admin'.

```php
use Ladder\Ladder;

Ladder::role('admin', 'Administrator', ['post:read']);

$role = Ladder::findRole('admin');
// $role instanceof Ladder\Role, $role->key === 'admin'
```

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

### Ladder::role()

Source: https://github.com/eneadm/ladder

Registers a role in the static registry. Populates the $roles static property with a Role object keyed by its slug.

```APIDOC
## Ladder::role()

### Description
Registers a role in the static registry. Populates the $roles static property with a Role object keyed by its slug.

### Method
Static method call

### Endpoint
`Ladder::role(...)`

### Parameters
#### Arguments
- **role** (Role) - Required - The role to register.

### Response
#### Success Response
- **void** - No return value.

```

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

### Manual registration in config/app.php

Source: https://github.com/eneadm/ladder

Use only if auto-discovery is disabled. Add Ladder\LadderServiceProvider::class to the providers array in config/app.php.

```php
// config/app.php — providers array
'providers' => [
    // ...
    Ladder\LadderServiceProvider::class,
],
```

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

### jsonSerialize(): array

Source: https://github.com/eneadm/ladder

Serializes the Role instance to an array with keys 'key', 'name', 'description', and 'permissions'. The 'name' and 'description' values are passed through Laravel's __() translator. Throws an Error if called before description() has been set.

```APIDOC
## `jsonSerialize`

### Description
Serializes the Role instance to an array. The 'name' and 'description' fields are wrapped in Laravel's `__()` translation helper; 'permissions' is returned as-is. Throws a PHP `Error` if invoked before `description()` has been called.

### Method
`jsonSerialize`

### Signature
```php
public function jsonSerialize(): array
```

### Parameters
None.

### Return Type
`array` with the following shape:
```php
[
    'key'         => $this->key,
    'name'        => __($this->name),          // passed through Laravel's __() translator
    'description' => __($this->description),   // passed through Laravel's __() translator
    'permissions' => $this->permissions,
]
```

### Throws
PHP `Error` if `jsonSerialize()` is invoked before `description()` has been called (uninitialized typed property).

### Request Example
```php
use Ladder\Ladder;

$role = Ladder::role('admin', 'Administrator', ['read', 'create'])
    ->description('Some admin description');

$serialized = $role->jsonSerialize();
// ['key' => 'admin', 'name' => 'Administrator', 'description' => 'Some admin description', 'permissions' => ['read', 'create']]

$json = json_encode($role); // JsonSerializable makes this equivalent to json_encode($role->jsonSerialize())
```

### Error Example
```php
use Ladder\Ladder;

$role = Ladder::role('admin', 'Administrator', ['read']);
// $role->description was never set:

try {
    $role->jsonSerialize();
} catch (\Error $e) {
    // "Typed property Ladder\Role::$description must not be accessed before initialization"
    $role->description('Fallback description');
    $serialized = $role->jsonSerialize(); // now safe
}
```
```

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

### findRole

Source: https://github.com/eneadm/ladder

Retrieves a registered role by its key. Returns null if the role is not found.

```APIDOC
## findRole

### Description
Retrieves a registered role by its key. Returns null if the role is not found.

### Method
`findRole`

### Signature
```php
public static function findRole(string $key): ?Role
```

### Parameters
- `$key` (string) - Required - The role key (slug) to look up, e.g. `'admin'`

### Return Type
`?Role` - the registered `Role` instance for `$key`, or `null` when no role with that key has been registered.

### Throws
None. A missing role yields `null`, never an exception.

### Request Example
```php
use Ladder\Ladder;

Ladder::role('admin', 'Administrator', ['post:read']);

$role = Ladder::findRole('admin');
// $role instanceof Ladder\Role, $role->key === 'admin'
```

### Response Example
```php
use Ladder\Ladder;

$role = Ladder::findRole('moderator'); // not registered

if ($role === null) {
    // No role definition exists for 'moderator' — fall back gracefully.
    return;
}
```
```

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

### hasPermissions

Source: https://github.com/eneadm/ladder

Checks whether at least one permission has been registered. Returns true if the permission list is non-empty.

```APIDOC
## hasPermissions

### Description
Checks whether at least one permission has been registered. Returns true if the permission list is non-empty.

### Method
`hasPermissions`

### Signature
```php
public static function hasPermissions(): bool
```

### Parameters
None.

### Return Type
`bool` - `true` when `count(static::$permissions) > 0`, i.e. at least one permission has been registered via `role()` or `permissions()`; `false` otherwise.

### Throws
None.

### Request Example
```php
use Ladder\Ladder;

if (Ladder::hasPermissions()) {
    // Some role has declared permissions; the registry is non-empty.
}
```
```

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

### Creating role assignment via factory

Source: https://github.com/eneadm/ladder

Uses UserRole::factory() to create a user with an associated role in tests. The 'roles' relationship is defined by the HasRoles trait.

```php
use App\Models\User;
use Ladder\Models\UserRole;

$user = User::factory()
    ->has(UserRole::factory(['role' => 'admin']), 'roles')
    ->create();
```

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

### Role::jsonSerialize() signature

Source: https://github.com/eneadm/ladder

Exact signature of the jsonSerialize() method from src/Role.php:28. Returns an array.

```php
public function jsonSerialize(): array
```

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

### HasRoles trait methods overview

Source: https://github.com/eneadm/ladder/blob/main/README.md

Lists the methods provided by the HasRoles trait. All method arguments can accept string, array, Collection, or Enum. For optimal performance, use array or Collection when handling multiple entries.

```php
// Access all of user's roles...
$user->roles : Illuminate\Database\Eloquent\Collection

// Determine if the user has the given role...
$user->hasRole($role) : bool

// Access all permissions for a given role belonging to the user...
$user->rolePermissions($role) : array

// Access all permissions belonging to the user...
$user->permissions() : Illuminate\Support\Collection

// Determine if the user role has a given permission...
$user->hasRolePermission($role, $permission) : bool

// Determine if the user has a given permission...
$user->hasPermission($permission) : bool
```

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

### hasRole with enum, array, and collection

Source: https://github.com/eneadm/ladder

Shows three interchangeable ways to pass roles: a BackedEnum case, an array of keys, or a Collection of UserRole pivot records (e.g. the $user->roles relation).

```php
// Enum (BackedEnum, e.g. enum Role: string { case ADMIN = 'admin'; })
if ($user->hasRole(Role::ADMIN)) {
    // ...
}

// Array of keys
if ($user->hasRole(['admin', 'editor'])) {
    // ...
}

// Collection of UserRole pivot records (the $user->roles relation itself)
if ($user->hasRole($user->roles)) {
    // ...
}
```

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

### Ladder::hasPermissions()

Source: https://github.com/eneadm/ladder

Checks whether the given permissions are present in the static $permissions list. Consumes the $permissions property.

```APIDOC
## Ladder::hasPermissions()

### Description
Checks whether the given permissions are present in the static $permissions list. Consumes the $permissions property.

### Method
Static method call

### Endpoint
`Ladder::hasPermissions(...)`

### Parameters
#### Arguments
- **permissions** (array) - Required - The permissions to check.

### Response
#### Success Response
- **bool** - Whether all permissions are present.

```

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

### Role::jsonSerialize() return shape

Source: https://github.com/eneadm/ladder

Exact return array shape from src/Role.php:30-35. Name and description are passed through Laravel's __() translator; permissions are returned as-is.

```php
[
    'key'         => $this->key,
    'name'        => __($this->name),          // passed through Laravel's __() translator
    'description' => __($this->description),   // passed through Laravel's __() translator
    'permissions' => $this->permissions,
]
```

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

### UserRole class declaration

Source: https://github.com/eneadm/ladder

Eloquent pivot model for the user_role table. Extends Pivot, uses HasFactory, and sets $incrementing to true for an auto-increment id primary key.

```php
class UserRole extends Pivot
{
    use HasFactory;

    public $incrementing = true;
}
```

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

### permissions

Source: https://github.com/eneadm/ladder

Returns a collection of all permission strings across the user's roles, deduplicated. Useful as a capability source for authorization checks.

```APIDOC
## `permissions`

### Description
Returns a collection of all permission strings across the user's roles, deduplicated. Useful as a capability source for authorization checks.

### Signature
```php
public function permissions(): Collection
```

### Parameters
None.

### Return Type
`Illuminate\Support\Collection` of permission strings — `collect($this->rolePermissions($this->roles))`: every permission across all of the user's roles, deduplicated. Unknown/legacy role keys contribute nothing.

### Throws
None.

### Request Example
```php
$permissions = $user->permissions();
// Illuminate\Support\Collection, e.g. ['read', 'create', 'update', 'delete']
```

### Request Example
```php
$permissions = $user->permissions()->toArray();

if (in_array('post:update', $permissions, true)) {
    // ...
}
```
```

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

### Creating a pivot row with null role

Source: https://github.com/eneadm/ladder

A pivot row with a null role is stored but filtered out by HasRoles::filterRoles(), so it never matches hasRole() or hasPermission() lookups.

```php
$user->roles()->create(['role' => null]); // stored, but never matches hasRole()/hasPermission() lookups
```

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

### Ladder::findRole()

Source: https://github.com/eneadm/ladder

Retrieves a registered role by its key (slug) from the static $roles property. Returns the Role object if found, otherwise null.

```APIDOC
## Ladder::findRole()

### Description
Retrieves a registered role by its key (slug) from the static $roles property. Returns the Role object if found, otherwise null.

### Method
Static method call

### Endpoint
`Ladder::findRole(...)`

### Parameters
#### Arguments
- **key** (string) - Required - The role key (slug) to look up.

### Response
#### Success Response
- **Role|null** - The Role object if found, otherwise null.

```

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

### UserRole model attribute shape

Source: https://github.com/eneadm/ladder

Defines the attribute shape for the UserRole pivot model, mapping to the user_role table. Columns include id, user_id, role, created_at, and updated_at, with id as an auto-incrementing primary key.

```php
[
    'id'         => int,     // auto-incrementing primary key ($incrementing = true)
    'user_id'    => int,     // foreignId
    'role'       => string|null, // nullable
    'created_at' => \Illuminate\Support\Carbon|null,
    'updated_at' => \Illuminate\Support\Carbon|null,
]
```

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

### Authorize request using hasPermission in policy

Source: https://github.com/eneadm/ladder/blob/main/README.md

Use the hasPermission method within authorization policies to check user's role permissions. Verifying granular permissions is more important than roles.

```php
/**
 * Determine whether the user can update a post.
 */
public function update(User $user, Post $post): bool
{
    return $user->hasPermission('post:update');
}
```

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

### rolePermissions multiple roles and unknown roles

Source: https://github.com/eneadm/ladder

Collects permissions across multiple roles. Roles stored on the user but not registered in Ladder::role() are silently ignored and contribute no entries.

```php
$permissions = $user->rolePermissions(['admin', 'editor']);

// A role stored on the user but never registered in Ladder::role() is silently ignored:
$permissions = $user->rolePermissions($user->roles);
// Unknown role keys simply do not contribute entries.
```

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

### rolePermissions

Source: https://github.com/eneadm/ladder

Collects permission strings for the given role key(s) by looking up the corresponding Role definitions and flattening their permissions. Returns a deduplicated array of permission strings.

```APIDOC
## `rolePermissions`

### Description
Collects permission strings for the given role key(s) by looking up the corresponding Role definitions and flattening their permissions. Returns a deduplicated array of permission strings.

### Method
`rolePermissions`

### Signature
```php
public function rolePermissions(string|array|Collection|UserRole|BackedEnum $roles): array
```

### Parameters
- `$roles` (string|array|Collection|UserRole|BackedEnum) - Required - Role key(s) whose permissions should be collected.

### Return Type
`array` of permission strings. For every matching pivot role, the corresponding `Role` definition's `permissions` are collected, then `->flatten()->unique()->toArray()` is applied. Roles without a registered definition contribute nothing. The result is deduplicated but not sorted; order follows role-definition and flatten order.

### Throws
none.

### Request Example
```php
$permissions = $user->rolePermissions('admin');
// e.g. ['post:read', 'post:create']
```

```php
$permissions = $user->rolePermissions(['admin', 'editor']);

// A role stored on the user but never registered in Ladder::role() is silently ignored:
$permissions = $user->rolePermissions($user->roles);
// Unknown role keys simply do not contribute entries.
```
```

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

### hasRole basic usage

Source: https://github.com/eneadm/ladder

Checks whether the user has the 'admin' role key.

```php
if ($user->hasRole('admin')) {
    // ...
}
```

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

### findRole basic usage

Source: https://github.com/eneadm/ladder

Retrieves a user and calls findRole on their first pivot record. Outputs the role name (e.g. 'Administrator') when the role is registered.

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

$role = $user->findRole($user->roles->first());
if ($role !== null) {
    echo $role->name; // e.g. 'Administrator'
}
```

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

### roles()

Source: https://github.com/eneadm/ladder

Defines the Eloquent HasMany relationship to the UserRole pivot model. Accessing $user->roles returns a collection of UserRole records for the user.

```APIDOC
## roles()

### Description
Defines the Eloquent HasMany relationship to the UserRole pivot model. Accessing `$user->roles` returns a collection of `UserRole` records for the user.

### Method
`roles()`

### Signature
```php
public function roles(): HasMany
```

### Parameters
None

### Return Type
`Illuminate\Database\Eloquent\Relations\HasMany`

### Throws
None

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

$user->roles()->updateOrCreate(['role' => 'admin']);
$user->roles()->create(['role' => 'editor']);
```

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

$user->roles; // Illuminate\Database\Eloquent\Collection of Ladder\Models\UserRole
```
```

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

### hasPermission

Source: https://github.com/eneadm/ladder

Checks whether the user has the given permission(s) across all assigned roles. Supports wildcard patterns and accepts a string, array, Collection, or BackedEnum.

```APIDOC
## `hasPermission`

### Description
Checks whether the user has the given permission(s) across all assigned roles. Supports wildcard patterns and accepts a string, array, Collection, or BackedEnum.

### Signature
```php
public function hasPermission(string|array|Collection|BackedEnum $permissions): bool
```

### Parameters
- `$permissions` (string|array|Collection|BackedEnum) - Required - Permission(s) to check.

### Return Type
`bool` — delegates to `hasRolePermission($this->roles, $permissions)`, i.e. checks the requested permission(s) against **all** of the user's assigned roles. Same wildcard rules as `hasRolePermission()`. This is the method recommended in the README for authorization policies.

### Throws
None.

### Request Example
```php
/**
 * Determine whether the user can update a post.
 */
public function update(User $user, Post $post): bool
{
    return $user->hasPermission('post:update');
}
```

### Request Example
```php
if ($user->hasPermission(['post:read', 'post:create'])) {
    // User can read OR create posts.
}

// With role permission '*' → hasPermission('anything') === true
// With role permission '*:create' → hasPermission('post:create') === true, hasPermission('post:read') === false
```
```

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

### filterRoles enums and empty results

Source: https://github.com/eneadm/ladder

Filters roles using a BackedEnum value. Use isEmpty() to check if the user holds none of the requested roles.

```php
$matched = $user->filterRoles(Role::ADMIN);

if ($matched->isEmpty()) {
    // User does not hold the requested role(s) — no UserRole pivot rows matched.
}
```

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

### rolePermissions signature

Source: https://github.com/eneadm/ladder

Signature of the rolePermissions method as defined in src/HasRoles.php:28.

```php
public function rolePermissions(string|array|Collection|UserRole|BackedEnum $roles): array
```

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

### findRole null guard for unregistered role

Source: https://github.com/eneadm/ladder

Handles a pivot row whose role key has no Ladder::role() definition. findRole returns null in that case, allowing graceful skipping.

```php
$pivot = $user->roles()->where('role', 'legacy-role')->first();

if ($pivot !== null) {
    $role = $user->findRole($pivot); // null when 'legacy-role' is not defined

    if ($role === null) {
        // Pivot row exists but no Ladder::role() definition — skip gracefully.
    }
}
```

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

### permissions method signature

Source: https://github.com/eneadm/ladder

Signature of the permissions method from src/HasRoles.php:86. Returns an Illuminate\Support\Collection of permission strings, deduplicated across all roles.

```php
public function permissions(): Collection
```
Tokens:
Raw