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:platform,admin,super_admin')->group(function () {
    Route::get('/ops', OpsController::class);
});

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

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

role:{alias},{value}[,{value2},...][,{column}] does strict match checks and accepts OR logic across multiple values.
role.min:{alias},{value}[,{column}] calls isAtLeast() when available on your enum.
For explicit columns, keep the column as the final parameter (example: role:org,owner,org_role).

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

User::whereRole('platform', 'admin')->get();
User::whereNotRole('platform', 'viewer')->get();
User::whereAtLeastRole('platform', 'admin')->get();

If an enum does not implement isAtLeast(), isAtLeastRole() throws UnsupportedOperationException. whereAtLeastRole() throws the same exception when the enum does not support hierarchy checks.

Enum options() helper

use Syftnex\RoleEnums\Concerns\ProvidesOptions;
use Syftnex\RoleEnums\Contracts\HasOptions;

enum PlatformRole: string implements HasOptions
{
    use ProvidesOptions;

    case SuperAdmin = 'super_admin';
    case Admin = 'admin';
    case Viewer = 'viewer';
}

PlatformRole::options();
// ['super_admin' => 'Super Admin', 'admin' => 'Admin', 'viewer' => 'Viewer']

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.

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