phpsoftbox / session

v1.0.0 2026-09-29 10:26 UTC

Requires

• php: ^8.5
• phpsoftbox/cookie: ^1.0
• psr/http-message: ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• phpsoftbox/cli-app: ^1.0
• phpsoftbox/cs-fixer: ^1.2.2
• phpsoftbox/database: ^1.0
• phpsoftbox/http-message: ^1.0
• phpunit/phpunit: ^13.3

Suggests

• phpsoftbox/database: Required for DatabaseSessionStore.

MIT

• Anton K.

Published on Packagist.org on 2026-09-29 10:34 UTC

README

Компонент для работы с сессиями.

Структура

• PhpSoftBox\Session — session API.
• PhpSoftBox\Session\Config — настройки session и cookie.
• PhpSoftBox\Session\Store — драйверы хранения session.
• PhpSoftBox\Session\Http — HTTP middleware.
• PhpSoftBox\Session\Maintenance — сервисные операции над хранилищем session.
• PhpSoftBox\Session\Cli — CLI-команды компонента.

Пример

use PhpSoftBox\Session\Session;
use PhpSoftBox\Session\Store\NativeSessionStore;

$session = new Session(new NativeSessionStore());
$session->start();

$session->set('user_id', 1);
$session->flash('notice', 'Saved');

$session->save();

DatabaseSessionStore

Если session нужно хранить в БД, используйте DatabaseSessionStore. Он читает session id из cookie, хранит payload в таблице sessions и обновляет cookie через общий CookieQueue.

use PhpSoftBox\Cookie\CookieQueue;
use PhpSoftBox\Session\Config\SessionConfig;
use PhpSoftBox\Session\Session;
use PhpSoftBox\Session\Store\DatabaseSessionStore;

$store = new DatabaseSessionStore(
    connections: $connections,
    cookies: new CookieQueue(),
    config: new SessionConfig(name: 'psb_session'),
    userIdKeys: [
        'web' => 'auth.user_id',
        'tenant' => 'tenant.auth.user_id',
    ],
);

$session = new Session($store);

userIdKeys связывает auth guard с ключом в payload сессии. Если ни один ключ не найден, store записывает guard=guest и user_id=NULL.

Безопасность и долгоживущие процессы:

• id из cookie принимается, только если он в формате генератора (64 hex) и такая сессия есть в таблице; неизвестный или некорректный id заменяется новым (useStrictMode, по умолчанию включён) — заранее известный id не становится сессией жертвы;
• сессия, неактивная дольше gcMaxLifetime (если не задан — lifetime, при lifetime > 0), не читается и удаляется сразу, не дожидаясь session:prune; без обеих настроек срок проверяет только session:prune;
• чтение и запись идут через write-соединение (реплика может отставать); одновременная вставка одной новой сессии не падает на уникальном индексе;
• после write() и destroy() состояние store сбрасывается — объект можно держать синглтоном в воркере.

Пример миграции лежит в database/migrations. В приложении её можно опубликовать через db:migrate:publish --package=phpsoftbox/session.

Очистка DB-сессий

DatabaseSessionStore не запускает PHP session GC автоматически. Для удаления старых записей используйте CLI-команду:

php psb session:prune --max-lifetime 86400

Сессия считается старой, если last_activity_datetime меньше текущего времени минус max-lifetime секунд. Если last_activity_datetime пустой, команда проверяет created_datetime. Без --max-lifetime используется SessionConfig::$gcMaxLifetime, а если он не задан — 1440 секунд.

Для проверки без удаления:

php psb session:prune --dry-run

Middleware

use PhpSoftBox\Session\Http\CsrfMiddleware;
use PhpSoftBox\Session\Http\SessionMiddleware;

$sessionMw = new SessionMiddleware($session);
$csrfMw = new CsrfMiddleware($session);

CsrfMiddleware отдаёт cookie XSRF-TOKEN через CookieQueue из атрибута запроса, а без CookieMiddleware — заголовком Set-Cookie ответа. В cookie уходит токен из сессии на момент ответа: если обработчик сменил его (вход, выход), клиент сразу получает новый.