The Most Advanced Laravel Permission Manager: Enterprise Authorization Engine with RBAC, ABAC, Role Hierarchy & Multi-Tenancy

composer require hosseinhezami/laravel-permission-manager

composer require hosseinhezami/laravel-permission-manager
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

use HosseinHezami\PermissionManager\Traits\PermissionTrait;

class User extends Authenticatable
{
    use PermissionTrait;
}

php artisan role:create admin "Administrator" "Full system access"
php artisan permission:create "users.view"
php artisan permission:create "users.edit"
php artisan role:assign-permission admin "users.view,users.edit"

$user->assignRole('admin');
$user->hasPermissionTo('users.view'); // true

$user->assignRole('admin');
$user->assignRole(['editor', 'manager']);
$user->revokeRole('editor');

$user->hasRole('admin');                        // true
$user->hasAnyRole(['admin', 'super-admin']);    // true
$user->hasAllRoles(['admin', 'manager']);       // true
$user->lacksRole('super-admin');                // true

// Grant direct permission
$user->givePermissionTo('reports.export');

// Check it
$user->hasDirectPermission('reports.export'); // true

// Deny directly
$user->denyPermissionTo('users.delete');

// Revoke
$user->revokePermissionTo('reports.export');

// Role grants all posts.* permissions
$editor->assignPermission('posts.*');

// But this specific user cannot delete
$user->denyPermissionTo('posts.delete');

// Result:
$user->hasPermissionTo('posts.edit');   // ✅ true (from role wildcard)
$user->hasPermissionTo('posts.delete'); // ❌ false (explicit deny wins)

1. Super Admin bypass
2. Explicit User DENY        ← highest
3. Explicit Role DENY
4. Explicit User ALLOW
5. Role ALLOW
6. Inherited Role permissions
7. Wildcard matching
8. Default: DENY             ← lowest

$role->assignPermission('users.*');        // All user operations
$role->assignPermission('*.edit');         // All edit operations
$role->assignPermission('admin.*');        // All admin operations
$role->assignPermission('!users.delete');  // Everything EXCEPT users.delete

// Build hierarchy: super-admin → admin → editor → viewer
$superAdmin->inheritFrom('admin');
$admin->inheritFrom('editor');
$editor->inheritFrom('viewer');

// Assign specific permissions at each level
$viewer->assignPermission('posts.view');
$editor->assignPermission('posts.edit');
$admin->assignPermission('posts.delete');
$superAdmin->assignPermission('system.config');

// A user with super-admin gets ALL permissions through the chain
$user->assignRole('super-admin');
$user->hasPermissionTo('posts.view');     // ✅ from viewer (3 levels up)
$user->hasPermissionTo('posts.edit');     // ✅ from editor (2 levels up)
$user->hasPermissionTo('posts.delete');   // ✅ from admin (1 level up)
$user->hasPermissionTo('system.config');  // ✅ from super-admin (direct)

$roleA->inheritFrom('roleB');
$roleB->inheritFrom('roleA'); 
// ❌ Throws CyclicRoleInheritanceException

// 24-hour access
$user->givePermissionTo('reports.export', 'allow', now()->addDay());

// 30-day contractor access
$user->givePermissionTo('projects.access', 'allow', now()->addDays(30));

// After expiration → automatically returns false
// No cron job needed for permission checks!

// Clean up expired records weekly
php artisan permission:prune --days=7

// config/permission-manager.php
'super_admin' => [
    'enabled' => true,
    'role_slug' => 'super-admin',
    'bypass_all' => true,
],

// Usage
$user->isSuperAdmin();                        // true
$user->hasPermissionTo('anything.xyz.123');   // true (bypasses everything)

// Create teams
$engineering = Team::createTeam(['name' => 'Engineering', 'slug' => 'engineering']);
$marketing = Team::createTeam(['name' => 'Marketing', 'slug' => 'marketing']);

// User joins both teams
$user->joinTeam($engineering);
$user->joinTeam($marketing);

// Different roles per team
$user->assignRoleForTeam('admin', $engineering);
$user->assignRoleForTeam('editor', $marketing);

// Check team-specific roles
$user->hasRoleForTeam('admin', $engineering);   // true
$user->hasRoleForTeam('admin', $marketing);     // false
$user->hasRoleForTeam('editor', $marketing);    // true

// Leave team
$user->leaveTeam($marketing);

// Via middleware
Route::middleware(['pm.team:header,X-Team-Id'])->group(function () {
    // All permissions scoped to team from X-Team-Id header
});

// Programmatically
PermissionManager::setTeam($currentTeam);
$user->hasPermissionTo('projects.view'); // Scoped to current team
PermissionManager::clearTeam();

// Only allow editing if user owns the post AND it's a draft
PermissionCondition::create([
    'permission_id' => $permission->id,
    'name' => 'owner-and-draft',
    'conditions' => [
        'all' => [
            ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.owner_id'],
            ['field' => 'resource.status', 'operator' => '=', 'value' => 'draft'],
        ],
    ],
]);

// Usage
$user->canPermission('posts.update', $post);
// Returns true ONLY if $user->id === $post->owner_id AND $post->status === 'draft'

// AND (all must match)
['all' => [...conditions]]

// OR (any must match)
['any' => [...conditions]]

// NOT (negate)
['not' => ...condition]

// Complex nesting
['all' => [
    ['field' => 'resource.status', 'operator' => '!=', 'value' => 'archived'],
    ['any' => [
        ['field' => 'user.id', 'operator' => '=', 'value' => 'resource.owner_id'],
        ['field' => 'user.role', 'operator' => '=', 'value' => 'admin'],
    ]],
]]

// Automatically logged when you:
$user->assignRole('admin');
$role->assignPermission('users.delete');
$user->givePermissionTo('reports.export');

// Query the audit trail
PermissionAudit::byActor($adminId)->get();
PermissionAudit::action('granted')->latest()->limit(50)->get();

// Each record includes:
// - actor_id (who made the change)
// - action (granted, revoked, created, etc.)
// - subject_type (user, role, permission)
// - ip_address, user_agent
// - metadata (JSON)

// config/permission-manager.php
'authorization_logging' => [
    'enabled' => true,
    'denied_only' => true,     // Only log failed attempts
    'sample_rate' => 0.1,      // Log 10% (for high-traffic apps)
],

// Create guard-specific roles
Role::create(['name' => 'Web Admin', 'slug' => 'web-admin', 'guard_name' => 'web']);
Role::create(['name' => 'API Admin', 'slug' => 'api-admin', 'guard_name' => 'api']);

// Query by guard
Role::forGuard('web')->get();
Role::forGuard('api')->get();
Permission::forGuard('api')->get();

// Groups (categories for UI)
$group = PermissionGroup::createGroup(['name' => 'User Management', 'slug' => 'user-mgmt']);
$permission->assignToGroup('user-mgmt');

// Sets (bundles for quick assignment)
$set = PermissionSet::createSet(['name' => 'Content Manager', 'slug' => 'content-manager']);
$set->assignPermissions(['posts.view', 'posts.create', 'posts.edit', 'posts.publish']);

// Assign entire set to a role
$role->assignPermissionSet('content-manager');

// These all work out of the box:
$user->can('users.edit');
$user->cannot('users.delete');

// In Blade
@can('users.edit')
    <button>Edit</button>
@endcan

// In Controllers
Gate::authorize('users.edit');
Gate::allows('users.edit');
Gate::denies('users.delete');

// Single permission
Route::get('/users', fn() => '...')
    ->middleware('pm:permission:users.view');

// ANY of these (OR logic)
Route::get('/users', fn() => '...')
    ->middleware('pm:permission:any:users.view|users.list');

// ALL of these (AND logic)
Route::post('/users', fn() => '...')
    ->middleware('pm:permission:all:users.view|users.create');

// NOT this permission
Route::get('/public', fn() => '...')
    ->middleware('pm:permission:not:admin.panel');

// Role checks
Route::get('/admin', fn() => '...')
    ->middleware('pm:role:admin|manager|editor');

// Combined (AND between directives)
Route::get('/reports', fn() => '...')
    ->middleware(['pm:role:admin', 'pm:permission:reports.view']);

@role('admin')
    <span>Welcome, Admin!</span>
@endrole

@permission('users.edit')
    <button>Edit User</button>
@endpermission

@hasanyrole(['admin', 'editor'])
    <span>You can edit content</span>
@endhasanyrole

@hasallroles(['verified', 'premium'])
    <span>Premium Verified User</span>
@endhasallroles

@unlesspermission('users.delete')
    <span class="text-muted">Delete disabled</span>
@endunlesspermission

@canpermission('posts.update', $post)
    <a href="{{ route('posts.edit', $post) }}">Edit</a>
@endcanpermission

PermissionManager::define('posts.update', function ($user, $post) {
    return $post->user_id === $user->id 
        || $user->hasPermissionTo('posts.edit.any');
});

// Usage
$user->canPermission('posts.update', $post);

$result = PermissionManager::explain($user, 'orders.delete');

// Returns:
[
    'allowed' => false,
    'ability' => 'orders.delete',
    'reason' => 'explicit_user_deny',
    'source' => 'direct_permission',
    'metadata' => [
        'matched_pattern' => 'orders.delete',
        'permission_id' => 42,
    ],
    'user' => [
        'id' => 1,
        'roles' => ['admin', 'editor'],
        'direct_permissions' => ['orders.view', '!orders.delete'],
    ],
]

$snapshot = PermissionManager::snapshot($user);
// Returns: roles, allow list, deny list, inherited roles, permissions, context

# 🩺 System health check
php artisan permission:doctor

# 🌳 View role hierarchy tree
php artisan permission:tree

# ❓ Why was access denied?
php artisan permission:why 42 users.delete

# 📋 Explain permission (JSON output)
php artisan permission:explain 42 users.edit --json

# ✅ Validate configuration
php artisan permission:validate

# ✂️ Prune expired permissions
php artisan permission:prune --days=30

# ⚡ Cache management
php artisan permission:cache:warm
php artisan permission:cache:clear

# 📦 Generate CRUD permissions
php artisan permission:generate-resource users

# 🔄 Sync routes (3 strategies)
php artisan permission:sync-routes --strategy=controller-action

# Standard CRUD
php artisan role:create admin "Administrator"
php artisan permission:create "users.view"
php artisan role:assign-permission admin "users.*"
php artisan user:assign-role 1 admin
php artisan role:export roles.json
php artisan role:import roles.json

$ php artisan permission:why 42 users.delete

┌─────────────────────────────────────────────────┐
│  Permission Decision Explanation                │
└─────────────────────────────────────────────────┘

  User:    42
  Ability: users.delete

  ✗ DENIED

  Reason:  explicit_user_deny
  Source:  direct_permission
  Details:
    - matched_pattern: users.delete
    - permission_id: 15

// When a permission changes:
// 1. Permission cache invalidated
// 2. All roles with that permission invalidated
// 3. All users with those roles invalidated

// Manual cache control
PermissionManager::cache()->flushAll();
PermissionManager::cache()->flushUser($userId);
PermissionManager::cache()->flushRole($roleId);

use HosseinHezami\PermissionManager\Testing\InteractsWithPermissions;
use HosseinHezami\PermissionManager\Testing\PermissionAssertions;

class PostControllerTest extends TestCase
{
    use InteractsWithPermissions;
    use PermissionAssertions;

    public function test_admin_can_edit_posts()
    {
        $admin = $this->createUserWithRoles(['admin']);

        $this->assertHasRole($admin, 'admin');
        $this->assertHasPermission($admin, 'posts.edit');
        $this->assertDoesNotHavePermission($admin, 'system.config');
    }

    public function test_unauthorized_gets_403()
    {
        $user = $this->createUser();

        $this->actingAs($user)
            ->get('/admin/users')
            ->assertStatus(403);
    }
}

use HosseinHezami\PermissionManager\Facades\PermissionManager;

// Roles
PermissionManager::roles()->list();
PermissionManager::roles()->create(['slug' => 'admin', 'name' => 'Administrator']);
PermissionManager::role('admin')->assignPermission('users.*');
PermissionManager::role('admin')->inheritFrom('editor');

// Permissions
PermissionManager::permissions()->create('users.view');
PermissionManager::permissions()->sync();
PermissionManager::permissions()->generateResource('posts');

// Users
PermissionManager::user($userId)->assignRole('admin');
PermissionManager::user($userId)->hasPermission('users.edit');

// Authorization
PermissionManager::check($user, 'users.edit');
PermissionManager::explain($user, 'orders.delete');
PermissionManager::snapshot($user);

// Teams
PermissionManager::setTeam($team);
PermissionManager::clearTeam();

// Cache
PermissionManager::cache()->flushAll();

Request → Middleware / Gate / Blade
              ↓
     AuthorizationManager
              ↓
    ┌─────────────────────┐
    │ 1. Super Admin?     │ → BYPASS
    │ 2. User DENY?       │ → DENY
    │ 3. Role DENY?       │ → DENY
    │ 4. User ALLOW?      │ → ALLOW
    │ 5. Role ALLOW?      │ → ALLOW
    │ 6. Inherited?       │ → ALLOW
    │ 7. Conditions?      │ → EVALUATE
    │ 8. Default          │ → DENY
    └─────────────────────┘
              ↓
     AuthorizationResult
     (allowed, reason, source, metadata)

roles                    permissions              permission_groups
role_permissions         user_roles               user_permissions
role_inherits            permission_sets           permission_set_items
teams                    team_user                permission_conditions
permission_audits        authorization_logs

src/
├── Authorization/       (9 files - Core engine)
├── Console/            (24 files - CLI commands)
├── Events/             (6 files)
├── Exceptions/         (6 files)
├── Handlers/           (2 files)
├── Listeners/          (2 files)
├── Middleware/         (3 files)
├── Models/             (10 files)
├── Proxies/            (2 files)
├── Services/           (2 files)
├── Support/            (5 files)
├── Testing/            (2 files)
├── Traits/             (1 file)
└── Root files          (2 files)

// Hierarchy: super-admin > admin > seller > customer
$seller->inheritFrom('customer');
$admin->inheritFrom('seller');

// Conditional: sellers can only edit their own products
PermissionCondition::create([
    'permission_id' => Permission::findByRoute('products.edit')->id,
    'conditions' => [
        'field' => 'user.id',
        'operator' => '=',
        'value' => 'resource.seller_id',
    ],
]);

$companyA = Team::createTeam(['name' => 'Company A']);
$companyB = Team::createTeam(['name' => 'Company B']);

$user->joinTeam($companyA);
$user->joinTeam($companyB);

$user->assignRoleForTeam('admin', $companyA);
$user->assignRoleForTeam('viewer', $companyB);

$contractor->givePermissionTo('projects.access', 'allow', now()->addDays(30));
$contractor->givePermissionTo('billing.view', 'allow', now()->addDays(7));
// Automatically expires. No cron job needed for checks.

// Managers can approve expenses under $1000
PermissionCondition::create([
    'permission_id' => Permission::findByRoute('expenses.approve')->id,
    'conditions' => [
        'all' => [
            ['field' => 'user.role', 'operator' => '=', 'value' => 'manager'],
            ['field' => 'resource.amount', 'operator' => '<=', 'value' => 1000],
        ],
    ],
]);

✅ Unit Tests        → WildcardMatcher, ConditionEvaluator, MiddlewareParser, CacheKeys
✅ Feature Tests     → Trait, Models, Middleware, Blade, Commands, Gate, Proxy
✅ Integration Tests → Hierarchy, Teams, ABAC, Expiry, Cache, Audit

composer test              # All 141 tests
composer test-unit         # Unit only
composer test-feature      # Feature only
composer test-integration  # Integration only

composer require hosseinhezami/laravel-permission-manager

php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="config"
php artisan vendor:publish --provider="HosseinHezami\PermissionManager\PermissionManagerServiceProvider" --tag="migrations"
php artisan migrate

// config/permission-manager.php
return [
    'cache_duration' => 60,
    'wildcards' => true,

    'super_admin' => [
        'enabled' => true,
        'role_slug' => 'super-admin',
        'bypass_all' => true,
    ],

    'teams' => ['enabled' => true],
    'audit' => ['enabled' => true, 'log_mutations' => true],
    'conditions' => ['enabled' => true],

    'authorization_logging' => [
        'enabled' => false,
        'denied_only' => true,
        'sample_rate' => 1.0,
    ],
];

composer require hosseinhezami/laravel-permission-manager