SystemRoles Docs

Getting Started

Quick Start

On this page

This walk-through takes a fresh install to a working permission check. It assumes you finished Installation, including making yourself the super admin.

1. Create a role#

  1. Open /systemroles/admin/roles.
  2. Click Add Role.
  3. Enter Role Name Editor. Leave Guard Name empty: it becomes editor (the name in snake case).
  4. Save.

The new role gets every permission that already exists, switched off.

2. Add a permission#

  1. On the roles list, click Manage on the Editor row.
  2. Click Add Permission.
  3. Fill in:
    • Permission Name: article.publish
    • Guard Name: article.publish
    • Permission: Yes
  4. Save.

Editor now has article.publish switched on. Every other role also gets an article.publish row, switched off, so the matrix stays complete. The super admin always passes every check, whatever its row says.

3. Give a user the role#

  1. Open /systemroles/admin/roles/users.
  2. Find the user and click Assign Permission (this button assigns a role).
  3. Choose Editor and save.

The change is stored in user_roles and logged in user_roles_history.

4. Check the permission in code#

PHP
use BabeRuka\SystemRoles\Services\SystemRolesService;

public function publish(Article $article)
{
    $roleId = SystemRolesService::roleIdForUser(auth()->id());

    abort_unless(SystemRolesService::roleHas($roleId, 'article.publish'), 403);

    $article->publish();

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

5. Or protect a whole route#

Create a small middleware once (full version in Protecting Routes with Middleware):

PHP
// app/Http/Middleware/HasPermission.php
namespace App\Http\Middleware;

use BabeRuka\SystemRoles\Services\SystemRolesService;
use Closure;
use Illuminate\Http\Request;

class HasPermission
{
    public function handle(Request $request, Closure $next, string $permission)
    {
        $roleId = SystemRolesService::roleIdForUser(optional($request->user())->getKey());

        abort_unless(SystemRolesService::roleHas($roleId, $permission), 403);

        return $next($request);
    }
}

Register the alias (Laravel 11/12, bootstrap/app.php):

PHP
->withMiddleware(function (Middleware $middleware) {
    $middleware->alias(['permission' => \App\Http\Middleware\HasPermission::class]);
})

Use it:

PHP
Route::post('/articles/{article}/publish', [ArticleController::class, 'publish'])
    ->middleware(['auth', 'permission:article.publish']);

That is the full loop: roles and permissions are managed on screen, and your code checks them.

Next steps#