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.
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 |