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

Documentation	Description
Installation	Detailed installation and setup guide
Configuration	All configuration options explained
Core Concepts	Understanding hierarchical delegation
Basic Usage	Common usage patterns
Advanced Usage	Batch operations, validation, caching
Middleware	Route protection middleware
Blade & Routes	Blade directives and route macros
Events	Domain events and listeners
Commands	Artisan console commands
Customization	Extending the package
API Reference	Complete method reference
Testing	Testing your implementation
Troubleshooting	Common issues and solutions

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

License

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

ordain / delegation

Maintainers

Details