From adb26273b27cbdd1f751d9c326bf716a7ed5413c Mon Sep 17 00:00:00 2001 From: Jared Date: Wed, 27 May 2026 12:04:31 +0400 Subject: [PATCH] docs: complete Session package docs for v3.0 --- v3.0/packages/session/adapters.md | 19 +++++++++++-------- v3.0/packages/session/contracts.md | 8 ++++++-- v3.0/packages/session/helpers.md | 3 ++- v3.0/packages/session/overview.md | 5 +++-- v3.0/packages/session/usage.md | 3 ++- 5 files changed, 24 insertions(+), 14 deletions(-) diff --git a/v3.0/packages/session/adapters.md b/v3.0/packages/session/adapters.md index 9077789..dcb1f4e 100644 --- a/v3.0/packages/session/adapters.md +++ b/v3.0/packages/session/adapters.md @@ -25,16 +25,17 @@ The native adapter: - starts a PHP session if one is not already active - keeps an internal `LAST_ACTIVITY` timestamp in the session -- destroys the session when the idle time exceeds `timeout` +- refreshes the session when the idle time is within `timeout` +- resets the active session when the idle time exceeds `timeout` - updates `LAST_ACTIVITY` on every initialization Practical effect: the timeout is checked when the adapter is initialized, not by a background cleanup process. ### Caveats -- `all()` includes the adapter's internal `LAST_ACTIVITY` key because it reads the full session storage -- if `session_start()` fails, resolution throws a session exception -- if the adapter tries to destroy an expired session and `session_destroy()` fails, resolution throws a session exception +- `all()` includes the adapter's internal `LAST_ACTIVITY` key because it reads the full session storage. +- Session values are stored as encrypted payloads, so direct inspection of the backing storage is best treated as transport data rather than app-level values. +- When PHP session startup or teardown raises an error, Session surfaces it as a session exception. ## Database adapter @@ -84,15 +85,17 @@ The database adapter: - creates a dynamic model for the configured table through the Model package - registers a custom PHP session save handler before starting the session -- stores the raw PHP session payload in `data` +- stores the PHP session payload in `data` - updates `ttl` to the current Unix timestamp on every write - deletes expired rows during garbage collection when `ttl < time() - max_lifetime` +Because Session encrypts and serializes values before they reach `$_SESSION`, the `data` column contains PHP's session payload format around encrypted value strings. + ### Caveats -- this adapter depends on the Database and Model packages being configured correctly -- expiry cleanup depends on PHP session garbage collection calling the handler's `gc()` method -- the package does not create the session table for you +- This adapter depends on the Database and Model packages being ready before the first `session('database')` call. +- Expiry cleanup runs when PHP session garbage collection calls the handler's `gc()` method. +- Create the session table as part of your database setup before you switch the default adapter. ## Choosing an adapter diff --git a/v3.0/packages/session/contracts.md b/v3.0/packages/session/contracts.md index 0c5fcf9..feab1cb 100644 --- a/v3.0/packages/session/contracts.md +++ b/v3.0/packages/session/contracts.md @@ -6,6 +6,8 @@ This page defines behavior you can rely on when integrating with Session. `session()` returns `Quantum\Session\Session`, which forwards supported calls to the active adapter. +The factory keeps one shared wrapper per adapter name for the current process, so repeated `session()` or `session('native')` calls reuse the same wrapper. + Unsupported method calls throw a session exception. ## Read/write contract @@ -15,6 +17,8 @@ Unsupported method calls throw a session exception. - `delete(string $key): void` - `all(): array` +Session serializes and encrypts values on write, then decrypts and unserializes them on read. Scalars and arrays round-trip through the API, while backend storage keeps the encoded payload. + Use Session APIs as the source of truth for values. ## Presence contract @@ -44,7 +48,7 @@ Because `get()` depends on `has()`, these values read back as `null`. - `flush(): void` clears storage and destroys session state - `getId(): ?string` returns current session ID when available -- `regenerateId(): bool` regenerates ID only when a session is active +- `regenerateId(): bool` regenerates the ID for the active session, reopens the adapter, and keeps the same adapter config Use `regenerateId()` after authentication or privilege changes. @@ -55,6 +59,6 @@ Supported adapter names: - `native` - `database` -Unknown adapter names fail during resolution. +Unknown adapter names raise a session exception during resolution. When no adapter is passed, resolution uses `session.default` config. diff --git a/v3.0/packages/session/helpers.md b/v3.0/packages/session/helpers.md index dade365..408629d 100644 --- a/v3.0/packages/session/helpers.md +++ b/v3.0/packages/session/helpers.md @@ -24,5 +24,6 @@ session('database')->set('cart_id', 'abc123'); - no adapter passed → uses `session.default` - adapter passed → resolves that backend (`native` or `database`) - returns a Session wrapper, not a raw adapter +- reuses the same wrapper for repeated calls to the same adapter in the current process -Prefer backend setup through configuration, not direct adapter construction. +Prefer backend setup through configuration, then call `session()` from application code. diff --git a/v3.0/packages/session/overview.md b/v3.0/packages/session/overview.md index f999305..f6924ef 100644 --- a/v3.0/packages/session/overview.md +++ b/v3.0/packages/session/overview.md @@ -2,7 +2,7 @@ Session provides a consistent API for request-scoped state, flash messages, and session ID management. -Use it when you need to persist small values between requests without coupling your code to raw `$_SESSION` access. +Use it when you need to persist small values between requests without coupling your code to raw `$_SESSION` access. Stored values are serialized and encrypted through the Encryption package, so session data round-trips as PHP values while backend storage stays opaque. ## What it provides @@ -33,9 +33,10 @@ When no adapter is passed, Session uses `session.default` from `config/session.p ## Operational constraints +- `session()` reuses one `Session` wrapper per adapter inside the current process. - `has()` treats empty-like values as missing (`null`, `false`, `0`, `'0'`, `''`). - `get()` depends on `has()`, so those values resolve as `null`. -- Use Session APIs for reads/writes instead of relying on backend storage format. +- Use Session APIs for reads and writes instead of relying on backend storage format. - Regenerate session IDs after authentication or privilege changes. ## Read next diff --git a/v3.0/packages/session/usage.md b/v3.0/packages/session/usage.md index 5429632..12fe955 100644 --- a/v3.0/packages/session/usage.md +++ b/v3.0/packages/session/usage.md @@ -52,4 +52,5 @@ Most apps should set `session.default` and call `session()` without args. - `has()` returns `false` for empty-like values (`0`, `false`, `''`, `null`). - Native adapter includes framework keys like `LAST_ACTIVITY` in `all()` output. -- Database adapter requires working DB/model setup before use. +- Session values are encrypted in storage, so inspect them through `session()->get()` or `session()->all()` when you need app-level values. +- Database adapter works best after the database connection, model layer, and session table are ready.