Users and Roles
Accounts, roles, and the dot-notation permissions that guard routes and templates.
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.