State

Session

Session lifecycle, flash messages, handler bindings a integrace do request flow.

Overview

Session module provides request-to-request state and flash message support. It registers a session abstraction (SessionInterface) backed by configurable storage drivers and a flash bag abstraction (FlashBagInterface).

Configuration

Session is configured in app/Config/Session.php under top-level key session.

return [
    'session' => [
        'driver' => Env::string('SESSION_DRIVER', 'native'),
        'cookie' => Env::string('SESSION_COOKIE', 'LEMONADE_SESSION'),
        'lifetime' => Env::int('SESSION_LIFETIME', 7200),
        'native' => [
            'path' => Env::string('SESSION_NATIVE_PATH', 'writable/sessions'),
        ],
        'file' => [
            'path' => Env::string('SESSION_FILE_PATH', 'writable/sessions'),
        ],
        'database' => [
            'table' => Env::string('SESSION_DB_TABLE', 'sessions'),
        ],
        'redis' => [
            'host' => Env::string('SESSION_REDIS_HOST', '127.0.0.1'),
            'port' => Env::int('SESSION_REDIS_PORT', 6379),
            'database' => Env::int('SESSION_REDIS_DB', 0),
            'password' => Env::string('SESSION_REDIS_PASSWORD', ''),
            'prefix' => Env::string('SESSION_REDIS_PREFIX', 'sess:'),
            'timeout' => (float) Env::string('SESSION_REDIS_TIMEOUT', '2.5'),
        ],
    ],
];

Registered services

SessionServiceProvider registers SessionStorageInterface (driver-dependent), SessionInterface (NativeSession), alias session, FlashBagInterface (SessionFlashBag), and alias flash. Supported configured drivers are native, file, database, redis.

Usage through dependency injection

Prefer constructor injection for application services.

final class CartState
{
    public function __construct(
        private readonly SessionInterface $session,
    ) {
    }

    public function storeUserId(int $userId): void
    {
        $this->session->set('user_id', $userId);
    }
}

Controller usage

Controller has built-in $this->flash() helper (FlashBagInterface). Session services outside controllers should be accessed through constructor injection.

$this->flash()->set('notice', 'Saved successfully.');
$notice = $this->flash()->pull('notice');

Flash messages

Flash data is stored in session key _flash. Use set/get/has/remove/pull/all/clear. pull() returns value and removes it immediately, which fits PRG workflows.

$this->flash()->set('contact.result', ['ok' => true]);

return $this->redirect('/contact');

// next request
$result = $this->flash()->pull('contact.result', ['ok' => false]);

Storage path

For native and file drivers, configured path is resolved through ApplicationContext::resolveSessionPath(). Relative values are mapped under storage writable area.

$path = $context->resolveSessionPath('writable/sessions');

HTTP lifecycle

Session starts lazily. Storage start() is called automatically on first session/flash operation (get, set, has, ...). There is no dedicated session-start middleware in current runtime.

CLI runtime

Session provider is part of common providers, but session state is typically irrelevant in CLI command workflows. Use CLI persistence mechanisms explicitly when needed.

Security notes

Session is not an authentication system by itself. Keep payload small, avoid storing unnecessary sensitive data, and review cookie/session settings (cookie, lifetime, storage driver) for production requirements.