README

Infrastructure package to use PHP Backed Enums as roles in Laravel.

This package ships infrastructure only. It does not ship any pre-defined roles.

Installation

composer require syftnex/laravel-role-enums

Publish package files:

php artisan vendor:publish --tag=role-enums

Configuration

config/role-enums.php

return [
    'middleware_alias' => 'role',
    'default_column' => 'role',
    'directives' => [
        'role' => 'role',
        'unless_role' => 'unlessRole',
        'end_unless_role' => 'endUnlessRole',
    ],
    'enums' => [
        'platform' => \App\Enums\PlatformRole::class,
        'org' => \App\Enums\OrgRole::class,
    ],
];

Route Middleware

Route::middleware('role:platform,super_admin')->group(function () {
    Route::get('/admin', AdminController::class);
});

Route::middleware('role:org,admin,org_role')->group(function () {
    Route::resource('/projects', ProjectController::class);
});

Route::middleware('role.min:platform,admin')->group(function () {
    Route::get('/ops', OpsController::class);
});

role:{alias},{value}[,{column}] does strict match checks.
role.min:{alias},{value}[,{column}] calls isAtLeast() when available on your enum.

Blade Directives

@role('org', 'admin')
    <button>Invite Member</button>
@endrole

@unlessRole('platform', 'restricted')
    <a href="/dashboard">Dashboard</a>
@endUnlessRole

Blade checks are guest-safe and return false when no user is authenticated.

Optional directive renaming in config:

'directives' => [
    'role' => 'roleCheck',
    'unless_role' => 'unlessRoleCheck',
    'end_unless_role' => 'endUnlessRoleCheck',
],

HasRole Trait

use Syftnex\RoleEnums\Traits\HasRole;

class User extends Authenticatable
{
    use HasRole;

    protected array $roleColumns = [
        'platform' => 'platform_role',
    ];

    protected $casts = [
        'platform_role' => \App\Enums\PlatformRole::class,
    ];
}

$user->hasRole('platform', 'super_admin');
$user->getRole('platform');
$user->isAtLeastRole('platform', 'admin');

If an enum does not implement isAtLeast(), isAtLeastRole() throws UnsupportedOperationException.

Generator

php artisan make:role-enum UserStatus --migration=users --trait

Generates:

app/Enums/UserStatus.php
database/migrations/*_add_user_status_to_users_table.php
app/Traits/HasUserStatusRole.php

Generated stubs are parseable PHP and include commented guidance for enum cases, optional hierarchy (isAtLeast), and model cast examples.

SyftnexApp Examples

These are illustrative examples only. The package itself remains enum-agnostic.

// config/role-enums.php
'enums' => [
    'platform' => \App\Enums\PlatformRole::class,
    'org' => \App\Enums\OrgRole::class,
],

// routes/web.php
Route::middleware('role:platform,super_admin')->group(function () {
    Route::get('/admin', AdminController::class);
});

Route::middleware('role:org,admin,org_role')->group(function () {
    Route::resource('/projects', ProjectController::class);
});

@role('org', 'admin')
    <button>Invite Member</button>
@endrole

@unlessRole('platform', 'restricted')
    <a href="/dashboard">Dashboard</a>
@endUnlessRole

// app/Models/User.php
use Syftnex\RoleEnums\Traits\HasRole;

class User extends Authenticatable
{
    use HasRole;

    protected array $roleColumns = [
        'platform' => 'platform_role',
        'org' => 'org_role',
    ];
}

What This Package Does Not Do

Does not ship pre-defined role enums or cases.
Does not create role/permission tables.
Does not define how roles map to permissions.
Does not replace Gates or Policies.

Quality Commands

composer test
composer lint
composer analyse
composer coverage

composer coverage requires an installed PHP coverage driver (xdebug or pcov).

syftnex / laravel-role-enums

Maintainers

Package info

Statistics

Security