Roles and permissions

Admin 0.21 adds Site → Roles (/admin/roles): change what each role may do, add roles, and see who holds them, without editing config/config.php. It needs flocms-core 2.4 and one migration.

composer require "hostkurd/flocms-admin:^0.21" -W   # brings flocms-core 2.4
php flo admin:install                               # adds the roles migration (nothing is overwritten)
php flo migrate                                     # creates admin_roles
php flo admin:doctor                                # checks it

The page needs the permission roles.manage. The skeleton's Super Admin has it through *; give it to another role on the page itself or in config/config.php.

How it works#

config/config.php stays the default: its roles, permissions and admin_access_roles are what you see on the page at first ("From config").

• Changing a config role saves a row in admin_roles for that role ("From config · changed"). Reset to default deletes the row and the config values apply again. Saving a role back to exactly its config values does the same.
• New roles live only in the table ("Custom"). They get the next free role number (4, 5, …); the number never changes, because users.role stores it.
• The package gives the result to flocms-core with Auth::loadRolesUsing(), once per request (one small query on requests that check a permission; none on pages that don't). So every check sees the same roles: the panel, the skeleton's login and controllers, your own controllers' $actionPermissions, Auth::can() in templates, the API.
• Permission changes apply on each person's next request. Panel access (who may open /admin at all) follows on the next session refresh, every admin request with the skeleton's default auth.refresh_interval of 0.
• When the table is missing or can't be read, or with 'roles' => false in config/admin.php, the config roles apply unchanged. That is also the emergency switch when nobody can log in: edit config/admin.php (no shell needed), fix the roles, switch it on again.

The list#

Each role with its level, panel access, number of users, number of permissions and source. Edit, Reset to default (changed config roles, asks first) and Delete (roles added in the panel) appear only where allowed. The top role shows Locked.

Editing a role#

The page has the permission grid on the left and the role's details on the right.

Details

• Name, per language (the language badge opens the other languages).
• Level: the role's rank. A higher level manages users of a lower one; it must stay below your own level.
• Can open the admin panel (admin_access_roles): off for roles used only on the public site.
• A summary, a note on where the role comes from, and the first users holding it.

The grid, built from what the panel knows, so a new resource gets a row without any code:

• A group switch saves its wildcard and ticks every box it covers, including resources added later. Turned off, the boxes stay ticked and can be changed one by one.
• Ticking Create, Edit or Delete also ticks View (the list is how a record is reached); unticking View clears the row.
• A box ticked through a wider pattern (*, a switch) is shown pale and changes with that pattern. Without JavaScript, turning a switch off keeps the permissions it covered as separate ticks.

Name your own permissions so they get a proper row instead of appearing under Other:

// config/admin.php
'roles' => [
    'permissions' => [
        'reports.export' => 'Export reports',      // or a lang key: 'admin.perm.export'
        'shop.refund' => 'Refund orders',
    ],
],

Safety rules#

The server enforces each rule; the page only hides what would be refused.

1. The top role is locked: the highest-level role holding * (Super Admin by default) can't be edited, reset or deleted on the page.
2. Only roles below your level: you can change, create and delete roles whose level is lower than yours. Your own role is read-only for you.
3. No giving what you don't hold: a box is enabled only for permissions you have; a wildcard only if you hold it or a wider one. Patterns you don't hold stay as they were when you save.
4. Levels stay below yours, so nobody creates a role that outranks them.
5. Someone keeps the keys: a save, reset or delete that would leave no active user with panel access and roles.manage is refused, and so is one made while the users table can't be read (it can't be checked).

Reset gives the config values back, so it is offered only when you could set them yourself: the config level below yours and every permission that changes held.

Role 0 (people who signed up on the website) can be given permissions for your own site code; while its panel access is on, its page shows a warning.

Deleting a role#

Only roles added in the panel can be deleted (config roles are reset). If users hold the role, the dialog asks which role they move to: a role below your level that you may give (with users.assign_role); the highest level at or below the deleted role's is preselected, a config role first. They move in the same transaction as the delete, so nobody keeps the deleted number, and a new role never gets a number users still hold. Without JavaScript, Delete opens a confirmation page.

Activity log and search#

Every change is an activity entry under Roles: name, level and panel access before → after, then Given and Taken away in words ("Posts → Edit", "All content"). Ctrl+K finds roles by name for people with roles.manage.

Levels and flocms-core 2.4#

Before 2.4 the role number was the rank, so a new role could not sit between Editor (1) and Admin (2). flocms-core 2.4 adds levels: Auth::canAssignRole() and Auth::canManageUser() compare Auth::level($role), which is the role number unless a level is set. The Roles page sets levels for the roles it stores; your own code can use Auth::level() and Auth::roles() (the names, including roles added in the panel).

Commands#

Upgrading the skeleton#

Skeleton 1.8.7 asks flocms-core for admin access at login (Auth::hasAdminAccess()), so a role added on the page can sign in at once. Older skeletons keep their own list of admin roles at login; FloCMS corrects the session on the next admin request (with auth.user_loader, which the skeleton sets), so it works there too, one redirect later.