hydrakit/session

Session library for Hydra PHP framework

v0.2.0 2026-07-09 20:02 UTC

Requires

• php: >=8.2
• hydrakit/core: ^0.2
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• phpunit/phpunit: ^11.0

MIT

• William Hleucka

Published on Packagist.org on 2026-07-09 20:02 UTC

README

A request-scoped key/value store that persists across requests for one client, backed by native $_SESSION behind two deliberately split interfaces. The data surface goes to controllers; the lifecycle surface is held only by the framework's session middleware.

The two surfaces

SessionInterface is everyday data — get/set/has/remove/all/clear, the id/regenerate controls for a privilege change, and flash/getFlash for values that live exactly one request. Falsy values ('0', 0, false, '') are real stored values; only an absent key is "missing".

SessionLifecycleInterface (start/save) is held only by StartSessionMiddleware, which opens the session on the way in and persists it on the way out. Keeping these methods off the data surface is the boundary: a controller literally cannot close the session early and lose later writes.

$session->set('cart', $items);
$session->flash('status', 'Saved.');     // readable only on the next request
$session->regenerate();                  // on a privilege change

Config

SessionConfig maps directly onto PHP's session cookie params and is built once from the environment. Defaults are safe-by-default for a first-party app: http-only, Lax same-site, session-length cookie. secure defaults to false so local http works out of the box — set SESSION_SECURE=true over https. Invalid combinations (a bad SameSite, or None without secure) fail loudly at construction rather than flowing silently into PHP.

Lifecycle and scope

Session data is only valid inside the window StartSessionMiddleware brackets around the request — every accessor throws LogicException outside it, so a read of stale state or a write that would never persist fails loud. The store is a request-scoped singleton and relies on Hydra building one container per request; see docs/one-container-per-request.md for the full contract and the worker-runtime boundary.