PHP 8.4: Calling session_set_save_handler() with more than 2 arguments deprecated

The session_set_save_handler function from the session extension sets a series of user-level session storage functions to override the built-in file-based storage mechanism. This is useful when an application needs to store user sessions in a database, in-memory, or to override the session storage mechanisms during automated tests.

The session_set_save_handler function supports two overloaded signatures, which is only possible for native built-in PHP functions, and only a handful of PHP functions leverage. Overloaded function signatures are being phrased out because function overloading is not a feature user-land PHP functions support, and given their problems in static analysis, documentation, validation, etc.

See the Deprecate functions with overloaded signatures RFC for other instances of overloaded functions.

session_set_save_handler function supports two signatures in PHP >= 5.4 and PHP < 9.0:

---

1. Pass individual callbacks

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

This function signature requires six callable parameters, and supports three optional callable parameters.

---

2. Pass a SessionHandlerInterface instance

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

The SessionHandlerInterface declares methods such as open, close, read, write, destroy, and gc that get called similar to the individual callback from the first signature.

Calling session_set_save_handler with more than two parameters deprecated

As part of the Deprecate functions with overloaded signatures RFC, the first signature of passing individual callbacks shown above is deprecated.

This means calling the session_set_save_handler function like the example below emits a deprecation notice:

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 ...

In PHP 9.0, PHP will no longer support this signature.

Recommended Replacement

Because calling the session_set_save_handler function with more than two parameters is deprecated in PHP 8.4, PHP applications should use the second signature shown above.

Applications that use individual functions to handle sessions will have to either declare a session handler class implementing the SessionHandlerInterface interface, or use an anonymous class.

---

Example of replacing callbacks with a single object instance of 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());

---

Here is an example that changes an existing six-callable signature to a SessionHandlerInterface signature by wrapping the same callbacks in an anonymous class. While this is the least possible change, it is recommended to create a new class implementing the SessionHandlerInterface interface and use it.

- 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);

The example above should be compatible with PHP 8.0 or later (due to the use of Union types). If the types were dropped, this implementation is cross-version compatible with PHP >= 5.4.

---

Backward Compatibility Impact

PHP 8.4 deprecates the overloaded signature variant of the session_set_save_handler function that accepts six or more individual callable values. Calling the deprecated signature emits a deprecation notice on PHP 8.4 and later.

The replacement can be made compatible with PHP 5.4+.

The overloaded signature will be removed in PHP 9.0, and attempting to call the session_set_save_handler function using the now-deprecated signature will emit a \TypeError exception.

---

RFC Discussion Implementation