README

Scoped authority delegation for Laravel. Enforce hierarchical permission boundaries where authority flows downward—users delegate subsets of their own grants, never more. Native escalation prevention with spatie/laravel-permission integration.

The Problem

Traditional RBAC answers: "What can this user do?"

This package answers: "What can this user grant to others?"

Without delegation control, a team lead could assign admin roles, create unlimited users, or manage users outside their hierarchy. This package prevents that.

Features

• Hierarchical user management - Users only manage users they created
• Role & permission delegation - Control which roles/permissions users can assign
• User creation quotas - Limit how many users each manager can create
• Native escalation prevention - Cannot grant more than you have
• Root admin bypass - Configurable super-user override
• Comprehensive audit logging - Track all delegation actions
• Domain events - React to delegation changes
• Built-in caching - Optimized for performance
• Multi-guard support - Works with custom authentication guards
• Blade directives & route macros - Convenient view and routing helpers
• Artisan commands - CLI tools for management
• Octane compatible - Ready for high-performance deployments

Requirements

• PHP 8.2+
• Laravel 11.x or 12.x
• spatie/laravel-permission ^6.0

Installation

Install the package via Composer:

composer require ordain/delegation

Publish and run the migrations:

php artisan vendor:publish --tag=delegation-migrations
php artisan migrate

Publish the configuration file:

php artisan vendor:publish --tag=delegation-config

Add the trait to your User model:

use Ordain\Delegation\Contracts\DelegatableUserInterface;
use Ordain\Delegation\Traits\HasDelegation;

class User extends Authenticatable implements DelegatableUserInterface
{
    use HasDelegation;

    protected $fillable = [
        // ... your fields
        'can_manage_users',
        'max_manageable_users',
        'created_by_user_id',
    ];
}

Quick Start

Check Authorization

use Ordain\Delegation\Facades\Delegation;

// Can this user assign a role to another user?
if (Delegation::canAssignRole($delegator, $role, $target)) {
    Delegation::delegateRole($delegator, $target, $role);
}

// Can this user create new users?
if (Delegation::canCreateUsers($user)) {
    // Create user...
}

// What roles can this user assign?
$assignableRoles = Delegation::getAssignableRoles($user);

Set Delegation Scope

use Ordain\Delegation\Domain\ValueObjects\DelegationScope;

// Define what a manager can delegate
$scope = new DelegationScope(
    canManageUsers: true,
    maxManageableUsers: 10,
    assignableRoleIds: [1, 2, 3],
    assignablePermissionIds: [4, 5],
);

Delegation::setDelegationScope($manager, $scope);

Protect Routes

// Using middleware
Route::middleware('can.delegate')->group(function () {
    Route::post('/users', [UserController::class, 'store']);
});

Route::middleware('can.assign.role:editor,moderator')
    ->post('/users/{user}/roles', [RoleController::class, 'store']);

// Using route macros
Route::post('/users', [UserController::class, 'store'])
    ->canDelegate();

Route::post('/users/{user}/roles', [RoleController::class, 'store'])
    ->canAssignRole(['editor', 'moderator']);

Blade Directives

@canDelegate
    <a href="{{ route('users.create') }}">Create User</a>
@endCanDelegate

@canAssignRole('admin')
    <option value="admin">Administrator</option>
@endCanAssignRole

Documentation

Artisan Commands

# Interactive installation wizard
php artisan delegation:install

# Display user's delegation scope
php artisan delegation:show {user}

# Assign role via CLI
php artisan delegation:assign {delegator} {target} {role}

# Clear delegation cache
php artisan delegation:cache-reset {user?}

# Health check
php artisan delegation:health

Testing

composer test

With coverage:

composer test-coverage

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Waqas Majeed
• All Contributors

License

The MIT License (MIT). Please see License File for more information.