Core

Session Service Provider

Session runtime, storage drivers and flash bag services.

Responsibility

Registers SessionStorageInterface, SessionInterface, NativeSession, alias session, FlashBagInterface, SessionFlashBag and alias flash. The provider selects storage from SessionConfig::$driver and exposes session/flash state to web controllers and request view helpers.

Session config

Application session config lives in app/Config/Session.yaml. YAML values are converted into typed SessionConfigDefinition; supported drivers are native, file, database and redis.

example.php
module: session
config:
  driver:
    $env: SESSION_DRIVER
    type: string
    default: native
  cookie:
    $env: SESSION_COOKIE
    type: string
    default: LEMONADE_SESSION
  lifetime:
    $env: SESSION_LIFETIME
    type: int
    default: 7200
  native:
    path:
      $env: SESSION_NATIVE_PATH
      type: string
      default: writable/sessions
  file:
    path:
      $env: SESSION_FILE_PATH
      type: string
      default: writable/sessions
  database:
    table:
      $env: SESSION_DB_TABLE
      type: string
      default: sessions
  redis:
    host:
      $env: SESSION_REDIS_HOST
      type: string
      default: 127.0.0.1
    port:
      $env: SESSION_REDIS_PORT
      type: int
      default: 6379
    database:
      $env: SESSION_REDIS_DB
      type: int
      default: 0
    password:
      $env: SESSION_REDIS_PASSWORD
      type: string
      default: ''
    prefix:
      $env: SESSION_REDIS_PREFIX
      type: string
      default: 'sess:'
    timeout:
      $env: SESSION_REDIS_TIMEOUT
      type: float
      default: 2.5

Storage drivers

native uses PHP session runtime with a configured save path. file stores serialized payloads in framework-managed files. database uses ConnectionInterface and the configured database table from SessionConfig. redis connects to configured Redis host/port/database/prefix. Unsupported driver names throw UnsupportedSessionDriverException.

Session service

SessionInterface exposes start(), started(), has(), get(), set(), remove(), clear() and regenerate(). NativeSession is the concrete session runtime and delegates to the configured storage.

example.php
use Lemonade\Framework\Session\Contract\SessionInterface;

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

    public function rememberCategory(string $category): void
    {
        $this->session->set('filter.category', $category);
    }

    public function category(): string
    {
        return (string) $this->session->get('filter.category', 'all');
    }
}

Flash bag

SessionFlashBag stores values in session key _flash. FlashBagInterface supports set(), get(), has(), remove(), pull(), all() and clear(); there are no typed helpers like success() or error() in the framework API.

example.php
use Lemonade\Framework\Session\Flash\FlashBagInterface;

final class ContactController
{
    public function __construct(
        private readonly FlashBagInterface $flash,
    ) {}

    public function submit(): ResponseInterface
    {
        $this->flash->set('contact.result', ['success' => true]);

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

Flash lifecycle

Flash data is stored in session for the next request after a redirect. get() reads without removing; pull() returns the value and removes it immediately, which is the usual pattern for one-time messages or old form input.

example.php
$this->flash()->set('notice', 'Saved successfully.');

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

// next request
$notice = $this->flash()->pull('notice');

Controller usage

Framework controllers expose flash access through AbstractController. Use the framework flash bag directly from controllers or inject FlashBagInterface into services that need request-to-request messages.

example.php
$this->flash()->set('notice', 'Saved successfully.');

if ($this->flash()->has('notice')) {
    $notice = $this->flash()->pull('notice');
}

View usage

ControllerServices creates RequestViewHelpers for views with optional session and flash services. Use $requestHelpers->flash() to pull one-time values in templates, or $requestHelpers->old() for old input stored under _old_input.* or flash key old_input.

example.php
<?php if (($notice = $requestHelpers->flash('notice')) !== null): ?>
    <div class="alert alert-success"><?= e($notice) ?></div>
<?php endif; ?>

<input name="email" value="<?= e($requestHelpers->old('email')) ?>">

Session lifecycle

Session storage starts lazily on first session operation. There is no dedicated session-start middleware in the current runtime; controllers, CSRF token manager, flash bag and request view helpers start session state by using the registered services.

Runtime scope

Sessions are for web/runtime state across requests, not persistent domain storage. Stateless API endpoints can avoid session/flash usage. Keep payloads small and store long-lived domain data in database/storage services instead.

Security relation

CSRF tokens are stored through SessionInterface, and flash messages use the same session runtime. The current session config documents cookie name, lifetime and driver-specific storage settings; secure/httpOnly/sameSite flags are not exposed in app/Config/Session.yaml.