HTTP sessions
Request::session() provides a separate Session object; session_start() is unnecessary. A cookie carries the identifier; the handler stores data. Configuration is worker-static, while data belongs to the instance.
Data and persistence
Section titled “Data and persistence”get($key, $default) uses ??: null returns the default. has() uses isset; exists() uses array_key_exists. set()/put() update values; put also accepts an array. delete()/forget() remove keys, pull() reads and removes, all() returns data and flush() clears it.
save() serializes changed data; a changed empty session invokes destroy. Reading disables object classes during unserialize. Unchanged data receives a timestamp update only with Session::$autoUpdateTimestamp; refresh() updates explicitly. gc() cleans using Session::$lifetime.
Current limitation: save ignores the bool returned by write/destroy and clears the dirty flag even on false. An explicit save exposes handler exceptions, but the destructor catches Throwable. A completed request therefore does not prove persistence. A handler can throw on failure; the application can explicitly save and handle errors before reporting success.
Storage
Section titled “Storage”Session::setHandler($instance)/handler($instance) install a SessionHandlerInterface. handlerClass($class, $config) validates the interface and resets the singleton. Interface methods: open, close, read, write, destroy, gc, updateTimestamp. The facade does not itself manage a full PHP session lifecycle through open/close.
The default FileSessionHandler uses session_save_path or the localzet-sessions temporary directory. Configure persistent, non-web-accessible storage with handlerClass(FileSessionHandler::class, ['save_path' => $path]). Temporary-file + rename writes prevent partial reads, not lost updates during concurrent read-modify-write. Multiple nodes require shared storage with defined concurrency behavior; it is not automatic.
Cookies and security
Section titled “Cookies and security”Session::setCookieParams() accepts lifetime/path/domain/secure/httponly/samesite; getCookieParams() returns the map. Initialization reads PHP ini: explicitly set the required policy before handling requests. Cookie lifetime differs from storage lifetime. See identifier management.
Sessions do not provide authorization, CSRF defense, login attempt limits or access revocation. Store minimal serializable data, not service/connection objects. GC is probabilistic, not an exact deletion schedule.