PHP 8.4: Вызов session_set_save_handler() с более чем 2 аргументами объявлен устаревшим

Функция session_set_save_handler из расширения session устанавливает ряд функций хранения сеансов на уровне пользователя, чтобы отменить встроенный механизм хранения в файлах. Это удобно, когда приложению требуется хранить пользовательские сессии в базе данных, в памяти или переопределять механизмы хранения сессий во время автоматизированных тестов.

Функция session_set_save_handler поддерживает две перегруженных сигнатуры, что возможно только для нативных встроенных функций PHP, и лишь немногие функции PHP поддерживают перегрузку. Перегруженные сигнатуры функций были исключены, потому что перегрузка функций не является возможностью, поддерживаемой пользовательскими PHP-функциями, и учитывая их проблемы со статическим анализом, документацией, валидацией и т.д.

Другие примеры перегруженных функций см. в PHP RFC: Deprecate functions with overloaded signatures.

Функция session_set_save_handler поддерживает две сигнатуры в PHP >= 5.4 и PHP < 9.0:

1. Передача отдельных обратных вызовов

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

   Эта сигнатура функции требует шесть callable параметров и поддерживает три необязательных callable параметра.

2. Передача экземпляра SessionHandlerInterface

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

   В интерфейсе SessionHandlerInterface объявлены такие методы, как open, close, read, write, destroy и gc, вызываемые аналогично индивидуальному обратному вызову из первой сигнатуры.

Вызов session_set_save_handler с более чем двумя параметрами объявлен устаревшим

В рамках PHP RFC: Deprecate functions with overloaded signatures первая сигнатура передачи отдельных обратных вызовов, показанная выше, объявлена устаревшей.

Это означает, что вызов функции session_set_save_handler, как в примере ниже, приводит к уведомлению об устаревании:

session_set_save_handler('my_session_open', 'my_session_close', 'my_session_read', 'my_session_write', 'my_session_destroy', 'my_session_gc');

// Deprecated: Calling session_set_save_handler() with more than 2 arguments is deprecated in ... on line ...

В PHP 9.0 поддержка этой сигнатуры будет прекращена.

Рекомендуемая замена

Поскольку вызов функции session_set_save_handler с более чем двумя параметрами устарел в PHP 8.4, PHP-приложениям следует использовать вторую сигнатуру, показанную выше.

Приложениям, использующим индивидуальные функции для обработки сеансов, придётся либо объявить класс обработчика сеансов, реализующий интерфейс SessionHandlerInterface, либо использовать анонимный класс.

Пример замены обратных вызовов одним экземпляром объекта SessionHandlerInterface:

-session_set_save_handler('my_session_open', 'my_session_close', 'my_session_read', 'my_session_write', 'my_session_destroy', 'my_session_gc');
+session_set_save_handler(new MySessionHandler());

Приведём пример, изменяющий существующую сигнатуру с шестью вызовами на сигнатуру SessionHandlerInterface, обернув те же самые обратные вызовы в анонимный класс. Хотя это наименьшее возможное изменение, рекомендуется создать новый класс, реализующий интерфейс SessionHandlerInterface, и использовать его.

-session_set_save_handler('my_session_open', 'my_session_close', 'my_session_read', 'my_session_write', 'my_session_destroy', 'my_session_gc');
+$sessionHandler = new class() implements SessionHandlerInterface {
+    public function open(string $path, string $name): bool {
+        return my_session_open($path, $name);
+    }
+
+    public function close(): bool {
+        return my_session_close();
+  }
+
+    public function read(string $id): string|false {
+        return my_session_read($id);
+    }
+
+    public function write(string $id, string $data): bool {
+        return my_session_write($id, $data);
+    }
+
+    public function destroy(string $id): bool {
+        return my_session_destroy($id);
+    }
+
+    public function gc(int $max_lifetime): int|false {
+        return my_session_gc($max_lifetime);
+    }
+};
+
+session_set_save_handler($sessionHandler);

Приведённый пример должен быть совместим с PHP 8.0 или более поздней версией (из-за использования Union типов). Если типы не используются, то данная реализация совместима с PHP >= 5.4.

Влияние на обратную совместимость

В PHP 8.4 устарел вариант перегруженной сигнатуры функции session_set_save_handler, принимающей шесть или более отдельных callable значений. Вызов устаревшей сигнатуры выдаёт уведомление об устаревании на PHP 8.4 и более поздних версиях.

Замена может быть совместима с PHP 5.4+.

Перегруженная сигнатура будет удалена в PHP 9.0, и попытка вызвать функцию session_set_save_handler с использованием устаревшей сигнатуры приведёт к возникновению исключения \TypeError.

• PHP RFC: Deprecate functions with overloaded signatures
• [RFC] [Discussion] Deprecate functions with overloaded signatures
• Реализация