Ladder for Laravel

Ladder supports wildcard patterns to grant broad access:

• *: Grants access to all permissions.
• *:create: Grants access to all 'create' permissions (e.g., post:create, user:create).
• *:update: Grants access to all 'update' permissions (e.g., post:update, user:update).

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

To enable role and permission management on your User model, add the Ladder\HasRoles trait to App\Models\User.

use Ladder\HasRoles;

class User extends Authenticatable
{
    use HasRoles;
}

When performing request authorization (e.g., in Laravel Policies), it is recommended to check for granular permissions using hasPermission() rather than checking for roles. Roles should primarily be used for UI presentation.

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

To install Ladder in your Laravel project (requires Laravel 12+), follow these steps:

1. Install the package via Composer:

   composer require eneadm/ladder

2. Initialize the Ladder service provider:

   php artisan ladder:install

3. Run migrations to create the user_role pivot table:

   php artisan migrate

Ladder includes an installation command to set up the necessary database migrations. Run the following command in your terminal to complete the setup:

php artisan ladder:install

Run the ladder:install command to set up the Ladder scaffolding in your Laravel application. This command performs the following actions:

1. Creates the App\Providers\LadderServiceProvider.php file by copying it from the package stubs into your application's app/Providers directory.
2. Automatically registers the LadderServiceProvider in your config/app.php file, ensuring it is loaded after the RouteServiceProvider.

php artisan ladder:install

Assign roles to a user by interacting with the roles relationship provided by the HasRoles trait. Use updateOrCreate to ensure the role is assigned without duplicates.

use App\Models\User;

$user = User::find(1);

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

Roles and their associated permissions are defined statically in App\Providers\LadderServiceProvider using the Ladder::role method. You specify a slug, a display name, an array of permissions, and an optional description.

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

The HasRoles trait provides several methods for interacting with roles and permissions. Method arguments can be strings, arrays, Collections, or Enums. For multiple entries, use arrays or Collections for better performance.

Use the ladder:show Artisan command to display a visual matrix of all roles and their assigned permissions in the terminal. Use the --style argument to change the table appearance.

# Display the matrix with different styles
php artisan ladder:show default
php artisan ladder:show borderless
php artisan ladder:show compact
php artisan ladder:show box

The Ladder class serves as the central registry for roles and permissions in the application. You can use it to define roles by providing a unique key, a display name, and an array of associated permissions. When a role is defined via Ladder::role(), the permissions are automatically merged into a global registry of unique, sorted permissions.

use Ladder\Ladder;

// Define a role with specific permissions
Ladder::role('admin', 'Administrator', ['edit_posts', 'delete_posts', 'manage_users']);

// Retrieve the role object
$adminRole = Ladder::findRole('admin');

The Role class implements JsonSerializable. When converted to JSON, the name and description fields are passed through the __() translation function. The resulting JSON structure contains the following keys:

• key: The unique identifier of the role.
• name: The translated display name.
• description: The translated description.
• permissions: The array of permission strings.

$role = new Role('admin', 'Administrator', ['*']);
$role->description('Full access');

echo json_encode($role);
// Output: {"key":"admin","name":"Administrator","description":"Full access","permissions":["*"]}