Session

Triangle Session подключает сессии Localzet Server к приложению Triangle: выбирает хранилище, применяет настройки cookie и предоставляет функцию session(). Это не обёртка над PHP session_start(): объект сессии принадлежит текущему HTTP-запросу, а параметры хранилища и cookie задаются для worker-процесса.

Установка и версии

composer require triangle/session

Компонент объявляет PHP ^8.1 и triangle/engine ^8.1. Engine этой ветки зависит от localzet/server ^4. Поведение Server 7.x нельзя автоматически считать поведением установленного приложения Triangle; сохраняйте lockfile и проверяйте версию Server при обновлении.

Чтение и запись

В обработчике запроса:

$session = $request->session();
$session->put('display_name', 'Reader');
$name = $session->get('display_name', 'Guest');
$session->forget('display_name');

Функция session() использует request()->session():

session(['preferences' => ['language' => 'ru']]);
$language = session('preferences.language', 'en');
$session = session();

Вызов с массивом записывает поля и возвращает null. Вызов без ключа возвращает объект сессии. Строковый ключ читает значение; второй аргумент — fallback, а не значение для записи.

Точечный путь обходит вложенные массивы через isset. Поэтому null в таком пути считается отсутствующим и заменяется fallback. Массив ['preferences.language' => 'ru'] записывает буквальный ключ с точкой, а не вложенную структуру: для записи вложенных данных передавайте вложенный массив, как в примере.

Вызов helper вне активного request не имеет контекста сессии. Не сохраняйте полученный объект в статическом поле сервиса и не используйте его для другого запроса.

Хранилище

Настройки находятся в session.php. Поставляемая конфигурация выбирает тип через SESSION_TYPE:

Тип	Обработчик	Настройки
file	FileSessionHandler	runtime/sessions по умолчанию
redis	RedisSessionHandler	host, port, auth, database, timeout, prefix
redis_cluster	RedisClusterSessionHandler	список узлов, auth, timeout, prefix
mongo	MongoSessionHandler	URL либо host/port, database, collection, options

File/Redis/RedisCluster — наследники обработчиков Server без собственного переопределения методов. Им нужны зависимости соответствующего Server и доступ к хранилищу. Mongo использует MongoDB Client; библиотека mongodb/mongodb и расширение mongodb должны присутствовать в приложении — прямой Composer require самого компонента их не устанавливает.

Неизвестный SESSION_TYPE не выбирает резервный handler: match в конфигурации завершится ошибкой. Тип и класс handler должны быть согласованы, потому что Bootstrap выбирает config по type, а класс — по handler.

Поставляемые значения: lifetime данных — 7 суток, cookie_lifetime — 365 суток, session_name — PHPSID, cookie_path — /, http_only — true, secure — false, same_site — пустая строка. Срок cookie не продлевает автоматически срок данных в хранилище.

Для HTTPS задайте SESSION_COOKIE_SECURE=true; SameSite и domain выберите под фактические домены приложения. Защиту изменяющих состояние cookie-запросов от CSRF нужно реализовать отдельно. После входа или повышения прав используйте ротацию session ID средствами установленного Server.

Bootstrap применяет только truthy значения конфигурации. Например, http_only=false, cookie_lifetime=0 или domain=” не сбрасывают уже установленное статическое значение. Это особенно существенно при нескольких bootstrap в одном процессе. Проверяйте фактические атрибуты Set-Cookie, а не только содержимое session.php.

Конкурентные запросы и сохранение

Обработчики хранят сериализованный снимок сессии. Атомарная запись файла не делает последовательность «прочитать, изменить, записать» транзакцией: параллельные запросы могут перезаписать изменения друг друга. Не используйте сессию как надёжный счётчик, очередь или финансовый журнал.

В Server 4.5.1 метод save не проверяет false, возвращённый handler->write. Успешное завершение запроса поэтому не является доказательством сохранения. Наблюдение за ошибками диска/хранилища и бизнес-данные с требованием надёжной записи должны иметь отдельный механизм.

MongoDB: границы обработчика

Mongo handler хранит _id, поля сессии и updated_at в одном документе; read возвращает сериализованный документ целиком, поэтому служебные поля попадают в данные сессии. Он не отбрасывает просроченный документ при read.

Gc вычисляет UTCDateTime из выражения time() - $maxLifetime * 1000: секунды и миллисекунды смешаны. На такую очистку нельзя полагаться как на реализацию заданного TTL. До отдельного исправления и проверки срока выбирайте другой handler либо реализуйте подтверждённую политику удаления просроченных данных. Само переключение SESSION_TYPE не создаёт TTL-индекс MongoDB.

Функция session

session(mixed $key = null, mixed $default = null): mixed объявляется только если функция с таким именем ещё не существует. При конфликте с другой библиотекой фактически может вызываться её helper; для однозначного доступа используйте текущий $request->session().

Вызов	Результат
`session()`	Объект сессии текущего request
`session(['name' => 'Reader'])`	Запись через put, результат null
`session('name', 'Guest')`	Значение либо fallback
`session('preferences.language', 'en')`	Обход вложенных значений, null заменяется fallback

Точки распознаются условием strpos, поэтому ключ с точкой в позиции 0 не обрабатывается как путь. Helper не поддерживает самостоятельную операцию удаления или вложенную запись через dot syntax.

Bootstrap

Triangle\Session\Bootstrap::start(?localzet\Server $server = null): void ничего не делает при null. При Server сначала вызывает Session::handlerClass с session.handler и session.config.{type}, затем назначает существующие статические свойства Session для truthy значений.

Ключ конфигурации	Свойство Server Session
auto_update_timestamp	autoUpdateTimestamp
cookie_lifetime	cookieLifetime
gc_probability	gcProbability
cookie_path	cookiePath
http_only	httpOnly
same_site	sameSite
lifetime	lifetime
domain	domain
secure	secure
session_name	name

Это настройки worker, а не отдельного пользователя. Компонент не проверяет схему конфигурации и не сбрасывает неподходящие/пустые поля в значения по умолчанию.

Обработчики

FileSessionHandler, RedisSessionHandler и RedisClusterSessionHandler наследуют соответствующие классы localzet Server. Их протокол, доступность драйверов и ошибки определяет установленная версия зависимости.

MongoSessionHandler принимает config в конструкторе. Методы open/close возвращают true; read ищет документ по _id, write выполняет replaceOne с upsert и обновляет updated_at; destroy удаляет документ, updateTimestamp обновляет метку; gc вызывает deleteMany по updated_at. MongoDB-исключения не преобразуются в собственный результат компонента.

Mongo write использует unserialize для данных handler-протокола. Это внутренний формат хранилища, а не endpoint для загрузки произвольной сериализованной строки от пользователя.

Install

Install переносит отсутствующий session.php из конфигурации пакета. Существующий файл не обновляется автоматически; сравнивайте новые параметры при обновлении зависимости.