Koldy PHP Framework — Session

Koldy\Session is a static facade for PHP session management with pluggable storage adapters.

Configuration

All top-level keys are read directly from configs/session.php. The options key is passed as-is to the adapter constructor.

// configs/session.php
return [
    'adapter_class' => \Koldy\Session\Adapter\File::class,
    'options' => [],               // passed to the adapter constructor

    'session_name' => 'your_app_name',  // PHP session name (cookie/header name)

    // Transport: how the session ID travels between client and server (see below)
    'transport' => [
        'type' => 'cookie',        // 'cookie' (default) or 'header'
    ],

    // Cookie options — only used when transport type is 'cookie'
    'cookie_life' => 0,            // 0 = until browser closes
    'cookie_path' => '/',
    'cookie_domain' => '',
    'cookie_secure' => false,
    'http_only' => false,
    'cookie_samesite' => 'Lax',    // optional: 'Strict', 'Lax', or 'None'
];

Transport

The transport setting controls how the session ID is passed between the client and the server. There are two modes: cookie (the default) and header.

Cookie Transport (default)

Session ID is stored in a browser cookie — the standard behaviour for web applications. When type is omitted, cookie is assumed.

'transport' => [
    'type' => 'cookie',
],

The following top-level config keys are applied as cookie parameters when cookie transport is active:

Key	Default	Description
`cookie_life`	`0`	Cookie lifetime in seconds (`0` = session cookie, deleted when browser closes)
`cookie_path`	`'/'`	The path on the server where the cookie is available
`cookie_domain`	`''`	Domain the cookie is available on (empty = current host only)
`cookie_secure`	`false`	Send cookie only over HTTPS when `true`
`http_only`	`false`	Prevent JavaScript access to cookie when `true`
`cookie_samesite`	(not set)	SameSite policy: `'Strict'`, `'Lax'`, or `'None'`

Header Transport

Session ID is passed in an HTTP request/response header instead of a cookie. This is useful for API-only applications, mobile clients, or any scenario where cookies are not practical (e.g. cross-origin SPAs, CLI consumers).

'transport' => [
    'type'        => 'header',
    'header_name' => 'X-Session',  // defaults to 'X-SESSION' if omitted
],

How it works:

On every response, the framework emits the current session ID as a response header:
```
X-Session: <session-id>
```
On subsequent requests, the client must send the session ID back in the same header:
```
X-Session: <session-id>
```
Cookie-related config keys (cookie_life, cookie_path, etc.) are ignored when header transport is active.

You can also pass the session ID explicitly when starting the session — useful when the client provides it through a non-standard mechanism:

Session::start($request->getHeader('X-Session'));

Session Lifecycle

use Koldy\Session;

Session::start();                     // initialize session
Session::start('custom-session-id');  // start with specific ID
Session::hasStarted();                // bool
Session::id();                        // current session ID

Session::close();      // flush data (no more writes allowed)
Session::isClosed();   // bool
Session::destroy();    // completely destroy session

Data Management

// Set and get
Session::set('user_id', 42);
$userId = Session::get('user_id');     // 42

// Check existence
Session::has('user_id');               // bool

// Set only if not already exists
Session::add('user_id', 42);          // only sets if key doesn't exist

// Delete
Session::delete('user_id');

// Get or compute and store
$cart = Session::getOrSet('cart', function () {
    return [];
});

Built-in Adapters

Adapter	Class	Description
File	`Session\Adapter\File`	File-based session storage (PHP default)
Db	`Session\Adapter\Db`	Database table session storage

Getting Config

$config = Session::getConfig();