SystemRoles Docs

Getting Started

Configuration

On this page

Settings live in config/systemroles.php. Publish the file to change them:

Bash
php artisan vendor:publish --tag=systemroles-config

Most settings can also be set in .env without publishing.

All settings#

Key .env variable Default What it does
controller_directory – app/Http/Controllers Folder scanned for controllers (Classes screen)
super_admin_role_id SYSTEMROLES_SUPER_ADMIN_ROLE_ID 1 The role that has every right and is the only one allowed into the admin area
user_model SYSTEMROLES_USER_MODEL App\Models\User Your Eloquent user model
route_middleware – ['web', 'auth', 'super_admin'] Middleware on every /systemroles/admin/* route
load_api_routes SYSTEMROLES_LOAD_API_ROUTES false Load the /api/systemroles/* routes
api_middleware – ['api', 'auth:sanctum', 'super_admin'] Middleware on the API routes
session_prefix SYSTEMROLES_SESSION_PREFIX '' Prefix added to every session key the package writes
scan_on_request SYSTEMROLES_SCAN_ON_REQUEST true Rescan controllers / routes when their admin screens open
dashboard_url SYSTEMROLES_DASHBOARD_URL /dashboard Where super_admin sends a logged-in user who is not the super admin
login_url SYSTEMROLES_LOGIN_URL /login Where super_admin sends a guest
user_manage_url SYSTEMROLES_USER_MANAGE_URL null Link for the "Manage" button on the Users screen. {id} is replaced with the user id

Settings in detail#

super_admin_role_id#

The super admin role:

  • passes every permission check (roleHas() always returns true);
  • gets every permission from permissionsForRole();
  • has access to every controller in checkSystemClassesInit();
  • is the only role the super_admin middleware lets through.

The default is 1, which matches the seeder. If your application already has roles and its super admin has another id, set it:

.env
SYSTEMROLES_SUPER_ADMIN_ROLE_ID=8

user_model#

The model used on the Users screen and in the user() relationships. Change it if your users live elsewhere:

.env
SYSTEMROLES_USER_MODEL="App\Domain\Accounts\Models\Account"

The model's table must still be users, because the Users screen reads users.id, name, email, email_verified_at, created_at and updated_at directly.

route_middleware#

Middleware on the admin area. The default requires a session (web), a logged-in user (auth) and the super admin role (super_admin). You can add your own, for example to require a verified email or two-factor login:

PHP
'route_middleware' => ['web', 'auth', 'verified', 'super_admin'],

Do not remove super_admin unless another middleware checks the same thing. Without it, any logged-in user can change roles.

load_api_routes and api_middleware#

The package has one API route, POST /api/systemroles/users/userdata (the user list data). It is off by default. Turn it on only if you build your own front end on top of it:

.env
SYSTEMROLES_LOAD_API_ROUTES=true

It is protected by api_middleware (Sanctum token + super admin by default).

session_prefix#

Some helper methods store the user's role in the session under keys such as role_id, role_name, user_role and user_permissions. If your app already uses those keys, set a prefix so they don't clash:

.env
SYSTEMROLES_SESSION_PREFIX="systemroles."

The keys then become systemroles.role_id and so on. Use SystemRolesService::sessionKey('role_id') to build the key in your own code.

scan_on_request#

When true, opening the Classes screen scans controller_directory and updates system_classes, and opening the Routes screen updates system_routes. This writes to the database and can be slow on large apps.

On large apps, turn it off and run the sync command after each deploy:

.env
SYSTEMROLES_SCAN_ON_REQUEST=false
Bash
php artisan systemroles:sync --classes

dashboard_url and login_url#

Redirect targets used by the super_admin middleware for browser requests. JSON requests get a 401 or 403 response instead.

user_manage_url#

Adds a "Manage" link on each row of the Users screen, pointing to your own user edit page:

.env
SYSTEMROLES_USER_MANAGE_URL="/admin/users/{id}/edit"

Example .env#

.env
SYSTEMROLES_SUPER_ADMIN_ROLE_ID=1
SYSTEMROLES_USER_MODEL="App\Models\User"
SYSTEMROLES_LOAD_API_ROUTES=false
SYSTEMROLES_SESSION_PREFIX="systemroles."
SYSTEMROLES_SCAN_ON_REQUEST=false
SYSTEMROLES_DASHBOARD_URL=/home
SYSTEMROLES_LOGIN_URL=/login
SYSTEMROLES_USER_MANAGE_URL="/admin/users/{id}/edit"

After changing config in production, run php artisan config:cache.