ez-php / session

2.5.6 2026-09-30 18:37 UTC

Requires

• php: ^8.5
• ez-php/contracts: ^2.0
• ez-php/http: ^2.0

Requires (Dev)

• ez-php/docker: ^2.0
• friendsofphp/php-cs-fixer: ^3.94
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^13.0

Suggests

• ext-redis: Needed for Driver\RedisSessionHandler
• ez-php/framework: Binds CsrfTokenStoreInterface → SessionCsrfTokenStore for CsrfMiddleware (by class-name string, only when installed)

MIT

• Andreas Uretschnig

• php
• session
• ez-php

Published on Packagist.org on 2026-09-30 18:43 UTC

README

Session handler drivers (File/Database/Redis/Array), StartSessionMiddleware, flash data, and session id regeneration for ez-php applications.

Installation

composer require ez-php/session

Usage

1. Register the service provider

$app->register(\EzPhp\Session\SessionServiceProvider::class);

2. Add StartSessionMiddleware before anything that reads the session

$app->middleware(\EzPhp\Session\StartSessionMiddleware::class);

Add it before ez-php/framework's CsrfMiddleware and before any ez-php/auth middleware — both read $_SESSION and assume a session is already active.

With ez-php/framework installed, SessionServiceProvider also binds CsrfTokenStoreInterface → SessionCsrfTokenStore, so CsrfMiddleware works without a binding of your own. A binding you register earlier is left alone; one you register later replaces it as usual.

3. Configure the driver

config/session.php:

<?php

return [
    'driver' => getenv('SESSION_DRIVER') ?: 'file',

    'file' => [
        'path' => sys_get_temp_dir() . '/ez-session',
    ],

    'database' => [
        'table' => 'sessions',
    ],

    'redis' => [
        'host' => getenv('SESSION_REDIS_HOST') ?: '127.0.0.1',
        'port' => (int) (getenv('SESSION_REDIS_PORT') ?: 6379),
        'database' => (int) (getenv('SESSION_REDIS_DATABASE') ?: 0),
        'ttl' => (int) (getenv('SESSION_REDIS_TTL') ?: 1440),
    ],

    // 0 disables periodic regeneration; StartSessionMiddleware otherwise
    // regenerates the session id once this many seconds have elapsed.
    'regenerate_interval' => (int) (getenv('SESSION_REGENERATE_INTERVAL') ?: 0),

    // Reject session ids the client chose (session fixation). Default: true.
    'strict_mode' => true,

    // Cookie settings passed to session_start(). All keys optional; defaults shown.
    'cookie' => [
        'name' => '',          // '' keeps PHP's session.name (PHPSESSID)
        'secure' => null,      // null = auto (Secure on HTTPS requests); true behind a TLS-terminating proxy
        'httponly' => true,
        'samesite' => 'Lax',
        'lifetime' => 0,       // 0 = until the browser closes
        'path' => '/',
        'domain' => '',
    ],
];

StartSessionMiddleware starts every session with these hardened settings instead of PHP's permissive defaults (no HttpOnly, no SameSite, use_strict_mode=0). Strict mode works because every bundled handler implements SessionUpdateTimestampHandlerInterface::validateId().

Driver	Value	Notes
Array	array	In-process only; for tests and CLI
File	file (default)	Files under session.file.path
Database	database	sessions table, created automatically
Redis	redis	Native TTL, no gc() sweep needed

4. Flash data

use EzPhp\Session\Flash;

Flash::set('message', 'Saved successfully.'); // readable on the *next* request
Flash::get('message');                        // readable on *this* request, one round only
Flash::keep('message');                       // extend it for one more request

5. Session id regeneration

use EzPhp\Session\SessionRegenerator;

SessionRegenerator::regenerate();                 // unconditional
SessionRegenerator::regenerateIfStale(1800);       // only if 30 minutes have passed

ez-php/auth already regenerates the id on login/logout itself — SessionRegenerator is for periodic regeneration of a long-lived session, independent of authentication.

License

MIT