User Management
User controller, account documents and collection availability.
Availability & Loading
The shared user controller resolves its context-specific collection during initialization. Without a
mapped user collection, isAvailable() is false and user lookups return no document. A
user
collection may exist without a group collection; in that case, user authentication can still work
but
group permissions are unavailable.
On an authenticated request, the authentication controller restores the user from the session, checks that the account is active and unlocked, and assigns the current user document.
User Document
The base user document contains email, username, normalized username key, password hash, active and verified states, assigned group IDs, account locking, 2FA providers and secret, recovery-code hashes, login timestamps and failed-attempt counters.
use Core\Registry;
use Core\User;
$user = Registry::get(User::class);
if ($user->isAuthenticated()) {
$document = $user->getDocument();
$email = $document?->getEmail();
}
Public API Reference
Core\User
Class & Registry
Class:
Core\User
Extends:
Core\User\Base
use Core\User;
use Core\Registry;
$user = Registry::get(User::class);
| Method | Description |
|---|---|
public function init(): void |
Initialize runtime user controller |
public function isAvailable(): bool |
Check if user subsystem is available |
public function isAuthenticated(): bool |
Check if runtime user is authenticated |
public function getDocument(): UserDocument|null |
Get current runtime user document |
public function setDocument(UserDocument|null $document): void |
Set current runtime user document |
public function getUserCollection(): UserCollection|null |
Get initialized user collection |
public function findByLogin(string $login): UserDocument|null |
Find user by login |
public function findActiveByLogin(string $login): UserDocument|null
|
Find active user by login |
public function has(string $permission): bool |
Check if current user group grants permission |
public function denies(string $permission): bool |
Check if current user group explicitly denies permission |
User Document
Class & Registry
use Core\User;
use Core\Registry;
$user = Registry::get(User::class);
$userDocument = $user->getDocument();
| Method | Description |
|---|---|
public function getEmail(): string |
Get email address |
public function setEmail(string $email): static |
Set email address |
public function getUsername(): string |
Get username |
public function setUsername(string $username): static |
Set username |
public function getUsernameKey(): string |
Get normalized username |
public function getPasswordHash(): string |
Get password hash |
public function setPasswordHash(string $passwordHash): static |
Set password hash |
public function isActive(): bool |
Get if user is active |
public function getActive(): bool |
Get active state |
public function setActive(bool $active): static |
Set active state |
public function isVerified(): bool |
Get if user is verified |
public function getVerified(): bool |
Get verification state |
public function setVerified(bool $verified): static |
Set verification state |
public function getGroupIds(): array |
Get assigned user group IDs |
public function setGroupIds(array $groupIds): static |
Set assigned user group IDs |
public function isLocked(): bool |
Get if user is locked |
public function getLocked(): bool |
Get lock state |
public function setLocked(bool $locked): static |
Set lock state |
public function isTwoFactorEnabled(): bool |
Get if two-factor authentication is enabled |
public function getTwoFactorEnabled(): bool |
Get two-factor authentication state |
public function setTwoFactorEnabled(bool $twoFactorEnabled): static
|
Set two-factor authentication state |
public function getTwoFactorProviders(): array |
Get two-factor authentication providers |
public function setTwoFactorProviders(array $twoFactorProviders):
static
|
Set two-factor authentication providers |
public function getTwoFactorSecret(): string|null |
Get two-factor authentication secret |
public function setTwoFactorSecret(string|null $twoFactorSecret):
static
|
Set two-factor authentication secret |
public function getRecoveryCodes(): array |
Get two-factor authentication recovery codes |
public function setRecoveryCodes(array $recoveryCodes): static |
Set two-factor authentication recovery codes |
public function getLastLogin(): DateTime|null |
Get last login |
public function setLastLogin(DateTime|null $lastLogin): static |
Set last login |
public function getLastFailedLogin(): DateTime|null |
Get last failed login |
public function setLastFailedLogin(DateTime|null $lastFailedLogin):
static
|
Set last failed login |
public function getFailedLoginAttempts(): int |
Get failed login attempts |
public function setFailedLoginAttempts(int $failedLoginAttempts):
static
|
Set failed login attempts |
public function increaseFailedLoginAttempts(): static |
Increase failed login attempts |
public function resetFailedLoginAttempts(): static |
Reset failed login attempts |
public function markLogin(): static |
Mark successful login |
Implementation Details
The following technical reference expands the existing guide with authentication lifecycle, state management, and provider behavior.
User Overview
Purpose
Core\User\Base is the shared APPNETOS runtime user controller.
It provides the current runtime user state and the central access layer to the mapped user collection.
The controller is intentionally small. It does not implement password verification, authentication sessions, two-factor authentication or trusted-device handling.
Responsibilities
Core\User\Base provides:
- Runtime user availability detection
- Access to the mapped user collection
- Current runtime user document
- User lookup by login
- Active user lookup by login
- Authentication-state detection
- Delegated group-based permission checks
Optional User Subsystem
The concrete user collection is provided by the mapped application or context child through:
protected function getCollection(): UserCollection|null
{
return null;
}
Returning null disables the user subsystem for the current runtime implementation.
This allows APPNETOS applications without user management or authentication to operate without unnecessary user collections or documents.
Runtime User State
A runtime user is represented by a Core\Document\User\Base document assigned to
Core\User.
$user->setDocument($document);
The user is considered authenticated when a runtime document exists:
$user->isAuthenticated();
The runtime user document can be accessed through:
$user->getDocument();
Collection Access
The mapped collection is available through:
$user->getUserCollection();
User lookup helpers:
$user->findByLogin($login);
$user->findActiveByLogin($login);
Separation of Responsibilities
Core\User
→ runtime user state and user access
Core\User\Auth
→ authentication workflow
Core\User\Group
→ groups and permissions
This separation keeps the runtime user controller lightweight and reusable across all APPNETOS contexts.
Runtime User
Overview
APPNETOS separates three different states:
Persistent User Document
Authentication Session
Runtime User
These states serve different purposes and must not be treated as interchangeable.
Persistent User Document
The persistent user document contains long-lived user data such as:
- Login identifier
- Password hash
- Active or locked state
- Group assignments
- Two-factor settings
- TOTP secret
- Recovery codes
The document itself does not mean that the user is authenticated.
Authentication Session
Core\User\Auth\Session stores the current authentication state.
A session may contain a valid user ID while authentication is still pending because two-factor authentication has not yet completed.
Example:
user ID = present
authenticated = false
twoFactorPending = true
Runtime User
Core\User only receives the user document after authentication is fully completed.
Without two-factor authentication:
Password verified
→ authenticated session
→ Core\User::setDocument()
With two-factor authentication:
Password verified
→ pending authentication session
→ no authenticated runtime user
→ 2FA successful
→ authenticated session
→ Core\User::setDocument()
This prevents downstream APPNETOS components from treating a password-only session as fully authenticated while a second factor is still pending.
Restoring an Existing Runtime User
During authentication initialization, APPNETOS attempts to restore the runtime user from the current authentication session.
The user is restored only when:
session is authenticated
user ID exists
user collection exists
user document exists
user is active
user is not locked
If the session references an invalid, inactive or locked user, the authentication session is invalidated.
Authentication Check
Application code should use:
$user->isAuthenticated();
or the shared authentication controller:
$auth->isAuthenticated();
The exact controller depends on whether the caller needs only runtime state or the complete authentication state.