Users and Roles

Accounts, roles, and the dot-notation permissions that guard routes and templates.

Updated
On this page

Users

A user is a folder at site/data/users/{shard}/{uuid}/ with an _index.json and a _data.json, the same split as a page. The shard is the first two characters of the uuid, so a large membership spreads over many folders. The username is in _index.json; the role and hashed password live in _data.json. $app->user($username) finds an account through the registry.

phlat user:create adam --role=admin
phlat user:role adam editor
phlat user:password adam

Roles

A role is a folder with an index.json listing permissions. A bare name is your own, and the framework's admin and guest apply when you have no role of that name:

phlat/roles/admin/index.json    ← ships with the framework
phlat/roles/guest/index.json
site/roles/editor/index.json    ← yours
{
    "locked": false,
    "permissions": {
        "admin": { "access": true },
        "pages": { "edit": true, "publish": true }
    }
}

Permissions are nested and checked with dot notation: pages.publish looks up permissions.pages.publish. A * key at any level is a wildcard for everything not listed there; the admin role is { "*": true }. A missing permission is denied.

A signed-out visitor is checked against the guest role, so can() and requirePermission() work the same for everyone. To grant guests a permission, add site/roles/guest/index.json. A site role replaces the framework's role of the same name.

An addon can ship roles too, named @alias/name (@shop/customer). Give a user one by that name, or build on it with extends, in site/roles/customer/index.json: { "extends": "@shop/customer", "fields": { … } }. The role's own keys replace the addon's, and its fields replace theirs by name. An addon role is complete on its own and never takes the shared roles/index.json.

Checking permissions

requirePermission() guards a route. It redirects to login when nobody is signed in and throws ForbiddenException (403) when the user lacks the permission:

$page->router->post('publish', function () use ($app, $page) {
    $app->session->requirePermission('pages.publish');
    // ...
});

requireLogin() accepts any signed-in user. can() checks without stopping the request:

if ($app->session->can('pages.edit')) { /* ... */ }

In Latte:

{if permission('pages.edit')}
    <a href="{$page->url()}/edit">Edit</a>
{/if}

Put checks in a before() hook to guard a whole section (see Routing). To restrict a page and everything under it to signed-in users or specific roles, set its access instead. See Publishing and access.

Profile fields

Extra user fields are declared in roles/index.json under fields, like a view declares page fields. Each name refers to a field in site/fields/, or extends one from the core or an addon ("avatar": { "extends": "@phlat/avatar" }), and values read like page fields. Only password is there by default: a field an addon needs, like oidc for sign-in with an identity provider or pinned for a user's own pinned pages, is listed here by you.

{
    "fields": {
        "password": { "extends": "@phlat/password", "required": true },
        "avatar": {},
        "jobTitle": {},
        "pinned": { "extends": "@dash/pinned" }
    }
}

Rate limiting

$app->session->throttle($key, $max, $window = 300) records one attempt for a key and returns true once more than $max attempts have been recorded within the window. Attempts are counted in SQLite, so concurrent requests each get their own number. Login uses it to slow repeated failures; use it for any form.