APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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.

Next Steps

Previous

User & Authentication

Explore User & Authentication

Next

Groups & Permissions

Explore Groups & Permissions