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

Session

Session lifecycle, storage, scope and typed data access without PHP native sessions.

Architecture

APPNETOS manages sessions inside its own core controllers without PHP $_SESSION. Sessions can be persisted as files or as MongoDB documents. Storage is selected by the concrete context implementation; the shared base defaults to file storage.

A cryptographically random 256-bit session identifier is sent using the logical SESSION cookie key through Core\Cookie. Cookie naming and scope are managed by the cookie controller.

Storage Backends

Backend Implementation
Filesystem APPNETOS_VAR/session; PHP files named with a 64-character hexadecimal session ID; exclusive locking on writes.
MongoDB Core\Document\AppnetosSession and the mapped Core\Collection\AppnetosSessionCollection.

Database storage requires a mapped collection. A shared session scope may be configured across compatible applications, but persisted database sessions are resolved by the session application identifier and base context.

Lifecycle

On initialization, the controller reads the logical session cookie, loads an active session or creates a new one, and registers shutdown persistence. Changed values are saved at shutdown. Session IDs can be regenerated without discarding session data. A session is destroyed when expired or explicitly removed.

The default timeout is 7,200 seconds. Session cookies are browser-session cookies by default; concrete implementations may enable persistent cookies. The default touch interval is 300 seconds.

Usage Example

use Core\Registry;
use Core\Session;

$session = Registry::get(Session::class);
$session->set('cart_id', 'cart-123');
$cartId = $session->getString('cart_id');
$session->remove('cart_id');

// Rotate the identifier after a security-sensitive transition.
$session->regenerate();

Expiration & Cleanup

The public cleanup() and destroyExpired() methods remove expired database records or matching session files. Expired sessions are also rejected when they are loaded.

Planned platform integration

A dedicated worker in appnetos-platform will periodically remove expired sessions. This worker is planned and is not yet part of the implemented standard runtime.

Security Considerations

Session IDs are generated using random_bytes(32). The controller supports rotation on login and other security transitions. Database session documents may store HMAC-derived IP and user-agent fingerprints, not raw values. The supplied base stores these fingerprints but does not itself enforce fingerprint matching when loading a session.

File-backed sessions require protected filesystem access and a shared persistent volume if multiple containers must read the same sessions. Do not place the session directory under a public web root.

Public API Reference

Core\Session

Class & Registry

Class: Core\Session

Extends: Core\Session\Base

use Core\Session;
use Core\Registry;

$session = Registry::get(Session::class);
Method Description
public function init(): void Initialize session controller
public function refresh(): void Refresh session
public function regenerate(): void Regenerate session
public function destroy(): void Destroy session
public function close(): void Close session
public function save(): void Save session
public function touch(): void Touch session lifetime
public function touchIfNeeded(int $seconds = 300): void Touch session if needed
public function shouldTouch(int $seconds = 300): bool Check if session should be touched
public function isExpired(): bool Check if session is expired
public function cleanup(): int Cleanup expired sessions
public function destroyExpired(): int Destroy expired sessions
public function set(string $key, mixed $value): void Set session variable
public function remove(string $key): void Remove session variable
public function clear(): void Clear all session variables
public function has(string $key): bool Check if session variable exists
public function get( string $key, mixed $default = null ): mixed Get session variable
public function getString(string $key): string Get session variable as string
public function getInt(string $key): int Get session variable as integer
public function getFloat(string $key): float Get session variable as float
public function getBool(string $key): bool Get session variable as boolean
public function getArray(string $key): array Get session variable as array
public function getAll(): stdClass Get all session variables
public function getId(): string Get session ID
public function getDocument(): AppnetosSession|null Get session document
public function getSessionTimeout(): int Get session timeout

Next Steps

Previous

Security

Explore Security

Next

User & Authentication

Explore User & Authentication