Access Control¶
ZubZet now includes significantly enhanced access control and permission capabilities. The system is built to provide a flexible and extensible authorization workflow, improved developer ergonomics, and full support for user-based and role-based permissions.
At its core, the access control system introduces two primary domain objects: User and Role. Permissions can be assigned directly to users or indirectly through roles. All permission checks automatically resolve the combined permission set.
UUIDs¶
Every user, role, group, organization, session and API key carries a UUID next to its numeric ID,
stored in the uuid column as a native MariaDB UUID and read back as an RFC 4122 string. It is the identifier meant to leave the
application: URLs, REST payloads and anything handed to a third party. Unlike the sequential ID, it
does not reveal how many records exist and cannot be guessed by counting up. The numeric ID stays the
internal key used for foreign keys and joins.
Every object that can be retrieved by ID can also be retrieved by UUID, and every object returns its own:
User::byUuid(string $uuid): ?User
Role::byUuids(string ...$uuids): array
$organization->uuid(): string
The UUID of the authenticated user is available without a lookup:
user()->uuid;
A session or API key has a UUID as well, and it is the only one of
its identifiers that is safe to hand out: the token authenticates whoever presents it, so it belongs
in a cookie or an Authorization header and nowhere else. Use the UUID to name a session in a "your
active sessions" list or to address one for renaming or invalidation. Like byId(), byUuid() is
scoped to the class it is called on - Session::byUuid() does not find an API key and
APIKey::byUuid() does not find a login.
User Object¶
The User object represents an application user and exposes a comprehensive API for retrieval, lifecycle management, and permission handling. Import it with use ZubZet\Framework\Authentication\Permission\User;: the global alias User is the request user instead, and Role, Group and Organization have no alias either.
User Retrieval¶
All retrieval methods are public static and return fully hydrated User objects. They only find active records; all() and byId() of Role, Group and Organization work the same way.
-
Returns all active users with an active assignment to the given role, directly or through their organization.
User::byGroup(Group $group)does the same for a group.User::byRole(Role $role): array -
Returns the active user with that email address or
null. Users without an email are never matched.User::byEmail(string $email): ?User -
Returns all active users that were not verified up to the given date:
verifiedisNULLor later than it.User::byNotVerified(DateTime $since): array -
Returns all active users that have all of the specified permissions. This includes user-based, role-based, group-based and organization permissions, which may come from different sources.
User::byAccessToAll(string ...$permissions): array -
Returns all active users that have at least one of the specified permissions. This includes user-based, role-based, group-based and organization permissions.
User::byAccessToAnyOf(string ...$permissions): array -
Returns all active users assigned to the given organization.
User::byOrganization(Organization $organization): array -
Returns all users.
User::all(): array -
Returns a user by its ID or
nullif not found.User::byId(int|string $id): ?User -
Returns all users matching the given IDs.
User::byIds(int ...$ids): array -
Returns a user by its UUID or
nullif not found.User::byUuid(string $uuid): ?User -
Returns all users matching the given UUIDs.
User::byUuids(string ...$uuids): array
Loading a User from Database Data¶
If a user instance needs to be created from an existing database row, the object can be hydrated manually.
-
Creates a user object from a raw
z_userrow, which must contain theidkey.$user = new User(array $data);
Creating a User¶
Users can be created through the static add method.
-
Creates a new user.
User::add(?string $email, ?string $password = null, ?DateTime $verified = null);
If no verification date is provided, the user is created as unverified.
Throws an InvalidArgumentException if the email is not a valid address or already belongs to another user. Passing null creates a user without an email. A password outside 3 to 1024 bytes throws InvalidArgumentException only after the user row is inserted, so that user stays without a password.
The $password parameter is optional. When it is omitted or null, the user is created without a password - useful for invite or SSO flows where a credential is set later via updatePassword().
Updating User Data¶
User attributes can be updated directly on the instance.
-
Updates the user’s email address. Throws an
InvalidArgumentExceptionif the address is not a valid email or already belongs to another user. Passingnullclears it. It updates only active rows and neither resetsverifiednor ends sessions.$user->updateEmail(?string $email); -
Updates the user’s password.
$user->updatePassword(string $password); -
Assigns the user to an organization (
z_user.organizationId), or unsets it whennullis passed. If the previous and/or the new organization has a linked permission group (seeOrganization::getGroup()), the user's group memberships are kept in sync: the previous organization's group is removed (even when it was assigned manually, and skipped when that organization is already removed) and the new organization's group is added. The user's fields are cleared.$user->updateOrganization(?Organization $organization); -
Clears all active login sessions for the user. Api keys are credentials of their own and are not touched.
$user->clearSessions();
Removing a User¶
Removing a user performs a soft delete.
-
Soft deletes the user (
active = 0) and nulls the object, so any further call on it,id()included, throwsInvalidArgumentException("Instance no longer exists"). Nothing else is touched, and the email stays taken (z_user.emailis unique, inactive users included): the user's roles, sessions, api keys and reset codes stay as they are. Existing sessions stop identifying the user as logged in anyway, because the login check requiresactive = 1; call$user->clearSessions()as well to end them.$user->remove();
Verification Handling¶
Verification status is time-aware and can be set or queried at arbitrary points in time.
-
Marks the user as verified, overwriting an earlier date. Defaults to
NOWif no date is provided.$user->verify(?DateTime $date = null); -
Checks whether the user was verified at a specific time:
truewhenverifiedis set and not later than$at(anystrtotimestring), so a future date counts as unverified now.$user->isVerified(string $at = "NOW"): bool
Two Factor¶
The account side of two factor authentication. The secret lives in z_user.two_factor_secret, and only a confirmed enrollment (two_factor_confirmed_at) turns two factor on.
-
Starts an enrollment: stores a fresh secret that does not count yet and returns it as a
ZubZet\Framework\Authentication\Totp.getSecret()andgetProvisioningUri()are the two shapes an authenticator takes it in. The label is the user's email and the issuer thepageName. Starting again replaces the secret and turns an active two factor off until the new one is confirmed, which is why the profile page refuses to start while two factor is on.$user->startTwoFactor(): Totp -
Turns two factor on when the code matches the stored secret. Returns
falsefor a wrong code and for an account that already has two factor.$user->confirmTwoFactor(string $code): bool -
Checks a code against the stored secret, one 30 second step either side of the current one. Returns
falsewhile the account has no secret.$user->verifyTwoFactorCode(string $code): bool -
Returns whether two factor is on, and since when.
$user->hasTwoFactor(): bool $user->twoFactorConfirmedAt(): ?string -
Turns two factor off and drops the secret.
$user->disableTwoFactor(): void
Login Tries¶
Failed logins are counted per account to rate-limit password guessing.
-
Returns
falsewhen the user has more failed tries thanmaxLoginTriesPerTimespanwithin the lastmaxLoginTriesTimespan. The event is logged asACCOUNT_LOGIN_RATE_LIMITED.maxLoginTriesTimespanis a relative time string such as3 minutes. When it is unset, the window start becomes1970-01-01, so every recorded try of the account counts, however old. WhenmaxLoginTriesPerTimespanis unset, it isnulland the comparison only passes for zero tries, so the account is blocked as soon as a single try is recorded in the window.$user->checkLoginTries(): bool -
Counts a failed login toward that limit.
$user->recordLoginTry(): void
if(!$user->checkLoginTries()) {
// blocked, notify the owner here if the application wants to
}
if(!$user->verifyPassword($password)) {
$user->recordLoginTry();
}
The framework does not notify the owner of a blocked login, an application does that itself where it needs to.
Role Assignment¶
Users can have multiple roles assigned or removed dynamically.
-
Adds one or more roles to the user and clears the user's cached fields. Adding a role the user already has inserts a duplicate row.
$user->rolesAdd(Role ...$roles); -
Removes one or more roles from the user (the assignment is set inactive) and clears the user's cached fields.
$user->rolesRemove(Role ...$roles); -
groupsAdd(Group ...$groups)andgroupsRemove(Group ...$groups)do the same for groups and reject plainRoleobjects.
User-Based Permissions¶
Permissions can be assigned directly to users in addition to role-based permissions.
-
Adds user-based permissions. Names are not deduplicated: an identical active row is inserted again.
$user->permissionsAdd(string ...$permissionNames); -
Removes user-based permissions.
$user->permissionsRemove(string ...$permissionNames);
Permission Checks¶
Permission checks always resolve the complete permission set. The permission methods (permissionsAdd, permissionsRemove, hasAccessAll, hasAccessAnyOf and the static buildPermissionVariants) come from the Permission trait that User, Role, Group and Organization share.
-
Checks whether the user has all specified permissions, wildcards included.
$user->hasAccessAll(string ...$permissionNames): boolWithout arguments it returns
true, since no permission is missing. -
Checks whether the user has at least one of the specified permissions, wildcards included.
$user->hasAccessAnyOf(string ...$permissionNames): boolWithout arguments it returns
false, since no permission can match.
Permission Retrieval and Refresh¶
-
Returns only user-based permissions.
$user->getUserPermissions(): array -
Returns all effective permissions (user-based + role-based + group-based), cached on the instance until a permission, role or group is changed through these objects, after which the getters re-query on every call. The rows look like
["name" => "x.y"], whileRole::getPermissions()returns plain strings. Only active role links, roles and permission rows count;z_user.activeis not filtered.$user->getPermissions(): array -
Reloads user-based permissions.
$user->refreshPermissions(); -
Reloads all permissions including roles. Changes made outside these objects (admin forms, direct SQL) only show up after this or
refresh().$user->refreshAllPermissions();
User Data & Utility Methods¶
-
Reloads the user data from the database and throws
RuntimeException("Object no longer exists")when the row is gone or inactive. Call it afterupdateEmail(),updatePassword(),verify()and role or group changes, which clear the object's fields; reading a field likeemail()before throwsField 'email' does not exist.$user->refresh(); -
Returns the user’s email address.
$user->email(): ?string -
Returns the verification timestamp.
$user->verified(): ?string -
Returns the user ID.
$user->id(): int -
Returns the user's UUID.
$user->uuid(): string -
Returns the user's active roles without groups, cached on the instance.
$user->getRoles(): array -
Returns the user's active groups, cached on the instance.
$user->getGroups(): array -
Returns the organization the user belongs to, or
nullif none is assigned. The result is cached on the instance - including thenullcase - untilclearFields()or a write operation invalidates it.$user->organization(): ?Organization -
Returns whether the user belongs to the given organization. A removed organization has no members.
$user->isMemberOf(Organization $organization): bool -
Returns the cached data of the user as an array. This is the full
z_userrow, including thepasswordhash and thesaltcolumn (nullfor natively hashed passwords), plus the internal cache keyspermissions,user-permissions,roles,groupsandorganization. Never output it unfiltered, for example in a response or a log; read single values withgetField()instead.$user->getAll(): array -
Throws an
InvalidArgumentException("Instance no longer exists") once the object was nulled byremove(); every other method on it throws the same.$user->checkInstance(): void
Role Object¶
The Role object represents a named collection of permissions that can be assigned to users. A Group is a Role restricted to z_role.is_group = 1: it grants permissions the same way, has all methods below (returning only groups, so Role::byId() never finds a group id), and is accepted wherever a Role is type-hinted. Role and group names share one unique column.
Role Retrieval¶
-
Returns all roles assigned to a user, including those of its organization.
Role::byUser(User $user): array -
Returns the active roles an organization holds.
Group::byOrganization(Organization $organization)does the same for groups.Role::byOrganization(Organization $organization): array -
Returns the active role with that exact name or
null.Role::byName(string $name): ?Role -
Returns all roles that have all specified permissions, wildcards included. Without arguments it returns all active roles.
Role::byAccessToAll(string ...$permissions): array -
Returns all roles that have at least one of the specified permissions, wildcards included.
Role::byAccessToAnyOf(string ...$permissions): array -
Returns all roles.
Role::all(): array -
Returns a role by ID.
Role::byId(int|string $id): ?Role -
Returns all roles matching the given IDs.
Role::byIds(int ...$ids): array -
Returns a role by its UUID or
nullif not found.Role::byUuid(string $uuid): ?Role -
Returns all roles matching the given UUIDs.
Role::byUuids(string ...$uuids): array
Role Creation and Loading¶
-
Creates a new role and returns it.
Role::add(string $roleName): Role; -
Creates a role from a raw
z_rolerow, which must contain theidkey.$role = new Role(array $data);
Updating and Removing Roles¶
-
Updates the role name. All fields are cleared, so call
$role->refresh()before reading the object again.$role->update(string $newName); -
Soft deletes the role. The instance is nulled, so any further call on it throws
InvalidArgumentException("Instance no longer exists"). Its permissions and user assignments stay but stop counting, and its name stays reserved.$role->remove();
Role Data Access¶
-
Returns the role's UUID.
$role->uuid(): string -
Returns the role name.
$role->name(): string -
Returns all active users assigned to the role, cached until
$role->refresh().$role->getUsers(): array
Role Permissions¶
-
Returns all permissions assigned to the role.
$role->getPermissions(): array -
Reloads role permissions.
$role->refreshPermissions(); -
Adds permissions to the role.
$role->permissionsAdd(string ...$permissionNames); -
Removes permissions from the role (soft delete).
$role->permissionsRemove(string ...$permissionNames); -
Replaces this role's permissions with the permissions of another role. The current permissions are removed and the source role's active permissions are copied over.
$role->setPermissionsByRole(Role $role);
Role Permission Checks¶
-
Checks whether the role has all specified permissions, wildcards included.
$role->hasAccessAll(string ...$permissionNames): boolWithout arguments it returns
true, since no permission is missing. -
Checks whether the role has at least one of the specified permissions, wildcards included.
$role->hasAccessAnyOf(string ...$permissionNames): boolWithout arguments it returns
false, since no permission can match.
Refreshing Role Data¶
-
Reloads the role data from the database.
$role->refresh();
Organization Object¶
The Organization object represents a group of users. Users can belong to at most one organization. An organization has a name (not unique, may be null) and is soft-deletable (active) like the other authentication objects. Like a user, it can hold permissions, roles and groups, which all its members inherit.
Organization Retrieval¶
-
Returns the organization a user belongs to, or
nullif the user has none. This is a convenience pass-through to$user->organization().Organization::byUser(User $user): ?Organization -
Returns all active organizations matching the given name. Names are not unique, so the result may contain zero, one, or multiple organizations.
Organization::byName(string $name): array -
Returns all organizations.
Organization::all(): array -
Returns an organization by its ID, or
nullif not found or inactive.Organization::byId(int|string $id): ?Organization -
Returns all organizations matching the given IDs.
Organization::byIds(int ...$ids): array -
Returns an organization by its UUID, or
nullif not found or inactive.Organization::byUuid(string $uuid): ?Organization -
Returns all organizations matching the given UUIDs.
Organization::byUuids(string ...$uuids): array -
Returns all active organizations that hold the role.
Organization::byGroup(Group $group)does the same for groups.Organization::byRole(Role $role): array -
Returns all active organizations that have all specified permissions, wildcards included, through their own permissions or their roles and groups.
Organization::byAccessToAll(string ...$permissions): array -
Returns all active organizations that have at least one of the specified permissions, wildcards included.
Organization::byAccessToAnyOf(string ...$permissions): array
Creating an Organization¶
-
Creates a new organization with the given name (which may be
null). When$createGroupistrue, a permissionGroupnamed$groupName, by default"{$name}_Group", is created and linked to the organization (z_organization.groupId,NULLwithout a group). The linked group is then available via$organization->getGroup()and is used byUser::updateOrganization()to sync group membership.$maxCapacitysets the maximum number of users,nullfor no limit.Organization::add(?string $name, bool $createGroup = false, ?string $groupName = null, ?int $maxCapacity = null): Organization
Updating and Removing Organizations¶
-
Updates the organization's name.
$organization->updateName(string $name); -
Sets the maximum number of users (
z_organization.max_capacity), ornullfor no limit. The framework counts active members plus open invitations of the self-management against it, assigning a user withupdateOrganization()is not limited.$organization->updateMaxCapacity(?int $maxCapacity); -
Soft deletes the organization (
active = 0). Its active members are detached first (organizationIdis set toNULLand the membership in the linked group is removed) and the linked group is deactivated, so$user->organization()returnsnullfor them.$organization->remove();
Organization Data Access¶
-
Returns the organization's UUID.
$organization->uuid(): string -
Returns the organization's name.
$organization->name(): string -
Returns the maximum number of users, or
nullfor no limit.$organization->maxCapacity(): ?int -
Returns all active users assigned to this organization.
$organization->getUsers(): array -
Reloads the cached users list.
$organization->refreshUsers(); -
Returns whether the given user belongs to this organization. The counterpart of
$user->isMemberOf().$organization->hasMember(User $user): bool -
Returns the permission
Grouplinked to this organization, ornullif none is linked. The result is cached on the instance untilclearFields()or a write operation invalidates it.$organization->getGroup(): ?Group -
Reloads the cached linked group.
$organization->refreshGroup();
Organization Roles and Groups¶
-
Adds one or more roles to the organization. Adding a role it already has inserts a duplicate row.
$organization->rolesAdd(Role ...$roles); -
Removes one or more roles from the organization (the assignment is set inactive).
$organization->rolesRemove(Role ...$roles); -
groupsAdd(Group ...$groups)andgroupsRemove(Group ...$groups)do the same for groups and reject plainRoleobjects. -
Returns only the roles, respectively only the groups, the organization holds. Neither is cached.
$organization->getRoles(): array $organization->getGroups(): array
Organization Permissions¶
Organization permissions are inherited by all its members.
-
Adds organization-based permissions. Names are not deduplicated: an identical active row is inserted again.
$organization->permissionsAdd(string ...$permissionNames); -
Removes organization-based permissions.
$organization->permissionsRemove(string ...$permissionNames); -
Checks whether the organization has all, respectively at least one, of the specified permissions, wildcards included, through its own permissions or its roles and groups.
$organization->hasAccessAll(string ...$permissionNames): bool $organization->hasAccessAnyOf(string ...$permissionNames): bool -
Returns the names of all effective permissions (own + role-based + group-based), each once, as plain strings like
Role::getPermissions().$organization->getPermissions(): array -
Reloads the permissions.
$organization->refreshPermissions();
Session Object¶
The Session object represents a login session (stored in z_logintoken) and provides methods for creation, retrieval, lifetime management, and invalidation. An api key is the same row with is_apikey set, represented by APIKey. The two are siblings, not parent and child: they get their behavior from the CanUseSession trait, so everything documented here applies to both. Type as Session|APIKey where either kind may turn up.
Session Retrieval¶
-
Returns a session by its token string, or
nullfor an unknown or invalidated token; an expired session that was not yet invalidated is still returned. The row decides the class, so a token belonging to an api key returns anAPIKey. This is the entry point of the authentication and therefore resolves both kinds, whichever class it is called on.Session::byToken(string $token): Session|APIKey|null -
Returns all active logins of a user, expired ones not yet invalidated included, or an empty array. Api keys are listed by
APIKey::byUser()instead.Session::byUser(User $user): array -
Returns a login by its ID, or
nullif the ID belongs to an api key.Session::byId(int|string $id): ?Session -
Returns all active logins matching the given IDs. Like
all()and the UUID finders, it skips invalidated rows.Session::byIds(int ...$ids): array -
Returns a login by its UUID, or
nullif the UUID belongs to an api key. This is the identifier to use when a session has to be addressed from outside the application - the token must not leave the client.Session::byUuid(string $uuid): ?Session -
Returns all logins matching the given UUIDs.
Session::byUuids(string ...$uuids): array -
Returns all active logins.
Session::all(): array
Creating a Session¶
-
Creates a new login session for a user. An optional
$userExeccan be passed to create an impersonation session where$useris the target user and$userExecis the acting. If omitted, both are set to$user. No cookie is sent; use$res->loginAs()for that. The optional$namelabels the session, which is what a "your active sessions" list shows, and$reasonrecords why it was created.Session::add(User $user, ?User $userExec = null, ?string $name = null, ?string $reason = null): Session -
Names the session, or removes its name when
nullis passed.$session->setName(?string $name): void -
Every session records the request that created it, without the caller doing anything:
deviceholds the user agent (cut to the 255 characters the column takes,nullwhen none was sent) andip_creationthe address it was created from. A name is never derived from either - it staysnulluntil someone chooses one.
API Keys¶
An api key is a session that is handed out deliberately instead of being
created by logging in. It carries the same token, authenticates the same way and
has the same lifetime controls -
APIKey shares all
of that with Session through the CanUseSession trait. What differs is that a
key belongs to a single user and has no executing user, so its add() takes
no $userExec. That is why the two are siblings rather than one extending the
other: PHP would not allow the narrower signature on a subclass.
$key = APIKey::add($user, name: "Deployment pipeline");
$key->setCanExpire(false); // from CanUseSession, like setName() and extend()
$key->token(); // the plain value the client sends as its z_login_token, known after add() or byToken()
APIKey::byUser($user); // the user's api keys
Session::byUser($user); // the user's logins
Every retriever is scoped to the class it is called on: Session::byId() does
not find an api key and APIKey::byId() does not find a login, the same way
Role and Group split the z_role table. The same holds for
APIKey::byUuid() and APIKey::byUuids(), which are the safe way to address a
key from outside the application - unlike the token, a UUID grants
nothing to whoever reads it.
byToken() is the one exception. It resolves both kinds whichever class it is
called on - returning an APIKey for a key and a plain Session for a login -
so an authenticating request is judged by the right rules without the caller
having to know which kind the token is.
-
Creates an api key for a user. The name is what keeps keys apart in a list, so it is worth passing.
APIKey::add(User $user, ?string $name = null, ?string $reason = null): APIKey
Everything else a key needs it already has as a session: it is named through
setName() and exempted from the login timeout through
setCanExpire(false), which is what most keys want.
-
The lifetimes the profile page offers for a new key next to Never expires, in days mapped to their label.
APIKey::LIFETIMES // [1 => "1 day", 3 => "3 days", ..., 365 => "1 year"]
Bearer Authentication¶
A client that cannot keep a cookie, like a script or another service, sends its token in the
Authorization header instead. Both a login and an api key authenticate this way.
Authorization: Bearer <token>
The bearer token wins over the z_login_token cookie. If it is invalid or expired the request is
anonymous, it does not fall back to the cookie.
Only a header that carries exactly one token counts as a bearer token. A header of another scheme,
like Basic, an empty Bearer, a value with more than one token like Bearer a b, and two
Authorization headers (Apache merges them into one comma separated value) carry no token. The
request then uses the cookie, if there is one. $req->bearerToken() returns the token of the
header, or null.
A valid session does not log a deactivated user in. Whichever way the token arrived, a session or an
api key, the request is anonymous ($user->isLoggedIn is false) as soon as the user's active is
0, for example after $user->remove(). The check runs on every request, so it
takes effect immediately without ending the session.
Lifetime Management¶
-
Extends the session's lifetime by the given number of seconds on top of the base timeout and any existing extension. This only changes server-side validity and needs an active row, so an invalidated session cannot be revived.
$session->extend(int $seconds): void -
Sets the total extension time in seconds, replacing any previously set extension.
$session->setExtensionTime(int $seconds): void -
Fixes the point in time the session expires, or hands it back to the computed lifetime when
nullis passed. A fixed expiry replaces that lifetime entirely: neitherloginTimeoutSecondsnorextended_secondshas a say while one is set, soextend()andsetExtensionTime()write an extension that does not move the expiry. Takes aDateTime, like$user->verify()does; the getters stay strings. The column is aTIMESTAMP, so the expiry has to fall inside its range - from 1970 up to2106-02-07 06:28:15UTC on the supported MariaDB versions. A date outside it is rejected by the database rather than silently truncated.$session->setExpiresAt(?DateTime $expiresAt): void$session->setExpiresAt(new DateTime("+30 days")); $session->setExpiresAt(null); // back to the computed lifetime -
Subjects the session to expiring, or exempts it from it. A session passed
falsenever expires and is therefore never invalidated on use, so exempting one revives a session that has expired but not yet been used. This is what turns an api key into a credential that keeps working, but it applies to any session. The exemption outranks a fixed expiry - it takes the session out of expiring altogether, rather than moving the point at which it does. It is stored inverted, in theis_permanentcolumn.$session->setCanExpire(bool $canExpire): void
The login cookie has its own lifetime
is_permanent and expires_at are server-side. loginAs() sets the
z_login_token cookie to expire after loginTimeoutSeconds (defaults to
7 days when unset) regardless, so a browser drops the cookie at that point
even though the session itself lives on. The expiry is fixed when the cookie
is set at login and is not re-issued when the session is extended, so
extend() and setExtensionTime() keep the session alive on the server but
not the cookie. Clients that send the token themselves are unaffected.
Invalidation¶
-
Immediately invalidates the session, preventing further use. The object is nulled, so any further call on it throws
InvalidArgumentException("Instance no longer exists").$session->invalidate(): void -
Ends every active login of a user in one statement, the session that issues it included. Api keys are credentials of their own and are left alone, so revoke those separately by calling
invalidate()on each ofAPIKey::byUser(). This is the static counterpart to$user->clearSessions(), which is also what$user->updatePassword()runs - changing a password ends every login of the account, its keys keep working.Session::clearForUser(User $user): void
Expiry Check¶
-
Returns
trueif the session has expired. A session exempt from expiring never is; otherwise the expiry is the one fixed on the session, or, when it carries none,createdplus the configuredloginTimeoutSeconds(defaults to 7 days) plus anyextended_seconds. The maths use PHP'sstrtotime()andtime()on the databasecreatedvalue, so PHP and database timezones must agree.$session->isExpired(): bool -
Returns the point in time the session becomes unusable, or
nullwhen the session is exempt from expiring. This is the effective expiry, whether it was fixed throughsetExpiresAt()or computed from the lifetime, which is absolute from creation and not sliding.$session->expiresAt(): ?string
Two Factor Checks¶
A session remembers when it last passed a two factor check, in z_logintoken.last_two_factor, and how many wrong codes it may still send, in remaining_two_factor_tries.
-
Returns whether the session has to pass two factor again.
falsefor an account without two factor,truewhile the session never passed a check or once the last one is older than$freshnessSeconds(defaults totwo_factor_freshness_seconds, 900). A session whose user is gone always has to. This is what$req->requireFreshTwoFactor()asks.$session->requireRenew(?int $freshnessSeconds = null): bool -
Returns when the session last passed a check, or
nullwhile it never did, and how many wrong codes it may still send (two_factor_triesto begin with, 5 by default).$session->lastTwoFactor(): ?string $session->remainingTwoFactorTries(): int -
Stamps a passed check on the session, and gives it its full budget of tries back.
$session->recordTwoFactor(): void $session->resetTwoFactorTries(): void -
Spends one try on a wrong code and returns how many are left. At zero the caller is expected to sign the session out, the framework's own endpoints do.
$session->spendTwoFactorTry(): int -
A login that verified the code itself stamps the new session right away.
$res->loginAs(int $userId, ?int $user_exec = null, ?string $name = null, ?string $reason = null, bool $recordTwoFactor = false)
Session Data¶
-
Returns the session's UUID. It is the only identifier of a session that is safe to hand out.
$session->uuid(): string -
Returns the plain session token, the value the client sends. Issued tokens are
zub-sha256-plus 64 hex characters, 75 in total, andz_logintoken.tokenstores onlyzub-sha256-plus the SHA-256 of the plain value. The plain value of a hashed token exists only on an object created byadd()orbyToken(); on one loaded by any other retriever it isnull. A token issued before hashing is stored as is and is still returned by every retriever, with a deprecation notice: compare againststoredToken()instead. Tokens issued before this format stay in plain text and keep working, so do not validate one by its length. Sessions are never deleted, only set toactive = 0(logout, expiry,clearSessions()).$session->token(): ?string -
Returns the value stored in
z_logintoken.token: the hash for a session issued in the new format, the plain token for an older one. Use it, orLoginToken::hash($token), when comparing in your own SQL.$session->storedToken(): string -
Returns the ID of the user who owns the session.
$session->userId(): ?int -
Returns the ID of the user being executed as (relevant for impersonation sessions).
$session->userIdExec(): ?int -
Returns the name of the session, or
nullif it has none.$session->name(): ?string -
Returns the user agent the session was started from, or
nullif none was sent.$session->device(): ?string -
Returns why the session was created, or
nullif no reason was given.$session->reason(): ?string -
Returns the address the session was created from, or
nullif none could be determined.$session->ipCreation(): ?string -
Returns the address the session was last used from, or
nullwhile it has not been used. It is rewritten on the first authenticated request that arrives from a different address, so a session that never moves is never written to.$session->ipLast(): ?string -
Returns whether the session is subject to expiring at all.
falsemeans it is exempt, which is whatsetCanExpire(false)does.$session->canExpire(): bool -
Returns the number of seconds the session has been extended by, or
nullif not extended.$session->extendedSeconds(): ?int -
Returns the creation timestamp of the session.
$session->created(): ?string -
Returns when the session was last used, or
nullwhile it has not been used since it was created. Every authenticated request refreshes it, but at most once persession_last_used_throttle_seconds(defaults to 60), so the timestamp costs one write per throttle window rather than one per request - read it as "last seen around then", not to the second. Set the key to0to write on every request. A request from a new address is always written, because that is what updatesipLast().$session->lastUsed(): ?string
Refreshing Session Data¶
-
Reloads the session data from the database. The getters return the loaded data without reloading, so call it after a setter such as
setName()orextend()to see the change.$session->refresh(): void