Roles

Roles live in the system_roles table and are managed at Admin → Roles (/systemroles/admin/roles).

The Roles screen#

The screen lists every role, ordered by sequence, with:

Column	Meaning
Role Name	The display name
Guard	The code name (`role_guard_name`)
Sequence	Sort order
# of Users	How many users have this role
Permissions	Every permission of the role as a badge: green when on, red when off
Action	A plus icon (Manage: opens the permission matrix) and a pencil icon (Edit Role)

If the system_roles table is empty when the screen opens, the four default roles (Super Admin, Admin, Manager, User) are created automatically.

Creating a role#

Click Add Role and fill in:

Field	Required	Rules
Role Name	Yes	Max 191 characters, unique
Guard Name	No	Max 191, unique. Left empty, it is built from the name: `Content Editor` → `content_editor`. It is always stored in lower snake case
Description	No	Max 255
Sequence	No	Integer. Left empty, the role goes to the end of the list

After saving, the role gets every existing permission, switched off.

Editing a role#

Click Edit Role. On edit, Guard Name is required and must stay unique. Changing a guard name does not update code that checks it, so search your code before renaming.

Deleting a role#

There is no delete button. Roles are linked by foreign keys (ON DELETE RESTRICT) from user_roles, system_roles_in, system_classes_in and system_routes_in, so a role cannot be removed while anything uses it.

To retire a role:

Move its users to another role on the Users screen.
Switch off its permissions.
Optionally rename it, for example Old Manager (unused).

If you must delete it, remove its rows from system_roles_in, system_classes_in, system_routes_in and user_roles first, then the role, in one database transaction.

Role ids matter#

Code often refers to roles by id, and the super admin is identified by id (super_admin_role_id). Treat role ids as permanent:

Don't reuse an id for a different role.
When moving data between environments, keep the same ids (the seeder inserts fixed ids 1–4 for this reason).

Columns you won't see on screen#

Column	Value
`role_lang_name`	Always `eng`. Reserved for translations
`role_role_class`	Always `RolesController`. Reserved

Doing it in code#

PHP

use BabeRuka\SystemRoles\Models\SystemRoles;

$role = SystemRoles::create([
    'role_name'       => 'Content Editor',
    'role_guard_name' => 'content_editor',
    'role_sequence'   => 5,
]);

$role->permissions;   // its system_roles_in rows
$role->userRoles;     // its user_roles rows

Creating a role from code does not fill in its permission rows (the admin screen does that). Opening the role's Manage screen once fills them, or you can copy them yourself. See Permissions.