SystemRoles Docs

Using SystemRoles in Your App

Checking Permissions in Code

On this page

All checks go through BabeRuka\SystemRoles\Services\SystemRolesService. Its helper methods are static, so you can call them anywhere.

The four questions#

PHP
use BabeRuka\SystemRoles\Services\SystemRolesService;

// 1. What is this user's role?
$roleId = SystemRolesService::roleIdForUser($user->id);      // int, 0 = no role

// 2. Is this user the super admin?
SystemRolesService::isSuperAdmin($user);                     // bool, defaults to auth()->user()

// 3. Does this role have this permission?
SystemRolesService::roleHas($roleId, 'invoice.approve');     // bool

// 4. Which permissions does this role have?
SystemRolesService::permissionsForRole($roleId);             // ['invoice.view' => 1, 'invoice.approve' => 0, ...]

roleHas() matches the permission's guard name or its name, and only counts rows switched on (in_role = '1'). The super admin always gets true.

A helper for "the current user can…"#

Most checks are about the logged-in user. Wrap the two calls once:

PHP
// app/helpers.php (autoload it via composer.json "files")
use BabeRuka\SystemRoles\Services\SystemRolesService;

if (! function_exists('can_do')) {
    function can_do(string $permission, $user = null): bool
    {
        $user ??= auth()->user();
        if (! $user) {
            return false;
        }
        return SystemRolesService::roleHas(SystemRolesService::roleIdForUser($user->getKey()), $permission);
    }
}
PHP
if (can_do('invoice.approve')) {
    // ...
}

In controllers#

PHP
public function approve(Invoice $invoice)
{
    abort_unless(can_do('invoice.approve'), 403);

    $invoice->approve();

    return back()->with('success', 'Invoice approved.');
}

Checking in the constructor for a whole controller:

PHP
public function __construct()
{
    $this->middleware('permission:invoice.view');
    $this->middleware('permission:invoice.approve')->only(['approve']);
}

(permission is the middleware from Protecting Routes with Middleware.)

Using the facade#

The SystemRoles facade resolves the same service:

PHP
use SystemRoles;

SystemRoles::isSuperAdmin();
SystemRoles::roleHas(3, 'invoice.approve');
SystemRoles::getUserRole($userId);   // UserRoles model or null
SystemRoles::role(3);                // SystemRoles model or null

Caching#

Each roleHas() call runs one small indexed query. For pages with many checks, load the role's permissions once per request:

PHP
$roleId = SystemRolesService::roleIdForUser(auth()->id());
$perms  = SystemRolesService::isSuperAdminRole($roleId)
    ? null                                                    // null = everything
    : collect(SystemRolesService::permissionsForRole($roleId))->filter()->keys()->all();

$can = fn (string $p) => $perms === null || in_array($p, $perms, true);

Or cache across requests, keyed by role, and clear the key when you edit that role's permissions:

PHP
$perms = cache()->remember("systemroles.perms.$roleId", 600, fn () =>
    SystemRolesService::permissionsForRole($roleId)
);

permissionsForRole() returns names (in_name). roleHas() also accepts guard names. If you cache, check by name.

Session helpers#

SystemRolesController has methods that store role data in the session. They are used by some host apps after login:

Method Stores
rolesArray($userId) role_id, role_name, role_guard_name, user_role
userRole() user_role (array with id, name, guard name)
userPermissions($roleId, $force = false) user_permissions (the result of permissionsForRole)

Keys get the session_prefix. Session copies do not refresh when you change roles or permissions, so a user may need to log in again to see changes. For security decisions, prefer the live checks above.