Устанавливает пользовательские обработчики хранения сессии

# session_set_save_handler

(PHP 4, PHP 5, PHP 7, PHP 8)

session_set_save_handler — Устанавливает пользовательские обработчики хранения сессии

### Описание

function session_set_save_handler(
callable `$open`,
callable `$close`,
callable `$read`,
callable `$write`,
callable `$destroy`,
callable `$gc`,
callable `$create_sid` = ?,
callable `$validate_sid` = ?,
callable `$update_timestamp` = ?
): bool

Также возможно зарегистрировать следующий прототип:

function session_set_save_handler(object `$sessionhandler`, bool `$register_shutdown` = `true`): bool

session_set_save_handler() устанавливает пользовательские обработчики хранения сессии, которые используются для сохранения и получения данных, связанных с сессией. Это особенно полезно, когда предпочтительным является метод хранения, отличный от тех, которые предоставляются сессиями PHP, например, хранение данных сессии в локальной базе данных.

### Список параметров

Данная функция имеет два определения (прототипа).

`sessionhandler`

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

`register_shutdown`

  Зарегистрировать session_write_close() как функцию register_shutdown_function().

или

`open`

  Callback-функция со следующей сигнатурой:

  function open(string `$savePath`, string `$sessionName`): bool

  Callback-функция `open` работает как конструктор в классах и выполняется при открытии сессии. Это первая callback-функция, которая выполняется, когда сессия стартует автоматически либо вручную через session_start(). Возвращаемое значение `true` в случае успешного выполнения, `false` в случае неудачи.

`close`

  Callback-функция со следующей сигнатурой:

  function close(): bool

  Callback-функция `close` работает как деструктор в классах и выполняется после того, как была вызвана callback-функция `write`. Она также вызывается при вызове session_write_close(). Возвращаемое значение должно быть `true` в случае успешного выполнения, `false` в случае неудачи.

`read`

  Callback-функция со следующей сигнатурой:

  function read(string `$sessionId`): string

  Callback-функция `read` должна всегда возвращать кодированную (сериализованную) строку сессии или пустую строку, если нет данных для чтения.

  Эта callback-функция вызывается внутренним механизмом PHP при старте сессии или при вызове session_start(). Перед тем, как будет вызвана эта callback-функция, PHP вызовет callback-функцию `open`.

  Возвращаемое значение данной callback-функции должно быть в точно таком же сериализованном формате, который изначально передавался для хранения в callback-функцию `write`. Возвращаемое значение будет автоматически десериализовано PHP и использовано для заполнения суперглобальной переменной $_SESSION. Даже если данные похожи на результат serialize(), стоит помнить, что это другой формат сериализации, который определён ini-директивой session.serialize_handler.

`write`

  Callback-функция со следующей сигнатурой:

  function write(string `$sessionId`, string `$data`): bool

  Callback-функция `write` вызывается, когда сессия должна быть сохранена и закрыта. Данная callback-функция принимает идентификатор текущей сессии и сериализованную версию суперглобальной переменной $_SESSION. Используемый внутри PHP метод сериализации определён ini-директивой session.serialize_handler.

  Переданные в эту callback-функцию сериализованные данные сессии должны быть сохранены в связи с переданным идентификатором сессии. При получении этих данных, callback-функция `read` должна вернуть то же самое значение, что было передано в callback-функцию `write`.

  Данная callback-функция вызывается, когда PHP завершает работу или явно при вызове session_write_close(). Следует помнить, что после выполнения этой callback-функции, PHP выполнит callback-функцию `close`.

  > Замечание:

  > Обработчик "write" не выполнится до тех пор, пока выходной поток не будет закрыт. Таким образом, вывод отладочных операторов в обработчике "write" никогда не отобразится в браузере. Если необходим вывод отладочной информации, рекомендуется записывать отладочные данные в файл.

`destroy`

  Callback-функция со следующей сигнатурой:

  function destroy(string `$sessionId`): bool

  Данная callback-функция вызывается, когда сессия уничтожается с помощью session_destroy() или при вызове session_regenerate_id() с параметром destroy, установленным в `true`. Возвращаемое значение должно быть `true` в случае успешного выполнения, `false` в случае неудачи.

`gc`

  Callback-функция со следующей сигнатурой:

  function gc(int `$lifetime`): bool

  Callback-функция сборщика мусора периодически вызывается PHP для очистки данных старых сессий. Частота контролируется директивами session.gc_probability и session.gc_divisor. Значение lifetime, которое передаётся в данную callback-функцию может быть установлено в session.gc_maxlifetime. Возвращаемое значение должно быть `true` в случае успешного выполнения, `false` в случае неудачи.

`create_sid`

  Callback-функция со следующей сигнатурой:

  function create_sid(): string

  Данная callback-функция выполняется, когда требуется новый идентификатор сессии. Не предусматривает параметров, а возвращаемое значение должно быть строкой, которая является допустимым идентификатором сессии для вашего обработчика.

`validate_sid`

  Callback-функция со следующей сигнатурой:

  function validate_sid(string `$key`): bool

  Callback-функция выполняется, когда должна быть запущена сессия, предоставляется идентификатор сессии и включается session.use_strict_mode. `key` - это идентификатор сессии для проверки. Идентификатор сессии действителен, если сессия с таким идентификатором уже существует. Возвращаемое значение должно быть `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

`update_timestamp`

  Callback-функция со следующей сигнатурой:

  function update_timestamp(string `$key`, string `$val`): bool

  Callback-функция выполняется при сессии. `key` - это идентификатор сессии, `val` - это данные сессии. Возвращаемое значение должно быть `true` в случае успешного выполнения или `false` в случае возникновения ошибки.

### Возвращаемые значения

Функция возвращает `true`, если выполнилась успешно, или `false`, если возникла ошибка.

### Список изменений

Версия | Описание
--- | ---
8.4.0 | Теперь вызов функции session_set_save_handler() с более чем двумя аргументами устарел. Вместо этого используйте сигнатуру с двумя аргументами.

### Примеры

Пример #1 Пользовательский обработчик сессии: полный код смотрите в описании SessionHandlerInterface.

Здесь только продемонстрирован вызов session_set_save_handler, полный пример можно посмотреть в описании SessionHandlerInterface.

Заметьте, что с session_set_save_handler() мы используем ООП-прототип и регистрируем функцию завершения, используя флаг параметра функции. Это обычно рекомендуется при регистрации объектов в качестве обработчиков хранения сессии.

    <?php
    class MySessionHandler implements SessionHandlerInterface
    {
        // здесь реализация интерфейса
    }

    $handler = new MySessionHandler();
    session_set_save_handler($handler, true);
    session_start();

    // устанавливаем и получаем значения по ключу из $_SESSION

### Примечания

Внимание

Обработчики `write` и `close` вызываются после деструктора объекта и поэтому не могут использовать его контекст или бросать исключения. Исключения не могут быть обработаны, так как не будут пойманы, не будет отражена трассировка стека исключения и выполнение просто прекратится неожиданно. Однако при этом, деструкторы объекта могут использовать сессии.

Можно вызвать session_write_close() из деструктора, чтобы решить эту проблему "курицы и яйца", но самый надёжный способ - это регистрировать функцию завершения, как описано выше.

Внимание

Текущий рабочий каталог изменяется некоторыми SAPI, если сессия закрывается при завершении скрипта. Завершить сессию можно раньше с помощью session_write_close().

### Смотрите также

- Директива session.save_handler
- Директива session.serialize_handler
- register_shutdown_function() - Регистрирует функцию, которая выполнится при завершении работы скрипта
- session_register_shutdown() - Регистрирует функцию завершения сессии
- Обратитесь к » save_handler.inc для полного набора рекомендаций по реализации

`↑` and `↓` to navigate • `Enter` to select • `Esc` to close • `/` to open