session_set_save_handler

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

session_set_save_handler — Set user-defined session storage function

illustrate

 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

You can register a custom session storage function using the following method:

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

session_set_save_handler() Sets a user-defined session storage function. If you want to use a method other than PHP's built-in session storage mechanism, you can use this function. For example, session storage functions can be customized to store session data to a database.

Parameters There are 2 prototypes of this function:

sessionhandler
An object that implements SessionHandlerInterface, SessionIdInterface (optional) and/or SessionUpdateTimestampHandlerInterface interfaces, such as SessionHandler.

register_shutdown
Register the function session_write_close() as the register_shutdown_function() function.

or
open(string $savePath, string $sessionName)
The following signature callable callback is implemented:

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

The open callback function is similar to the class constructor and will be called when the session is opened. This is the first callback function to start the session automatically or manually start the session by calling session_start(). This callback function operation returns true successfully, otherwise false.

Close
The close callback function is similar to the class's destructor. Called after the write callback function is called. The close callback function is also called after the session_write_close() function is called. This callback function operation returns true successfully, otherwise false.

read
The following signature callable callback is implemented:

 read(string $sessionId): string

If there is data in the session, the read callback function must return a string encoded (serialized) of the session data. If there is no data in the session, the read callback function returns an empty string.

After automatically starting the session or manually starting the session by calling the session_start() function, PHP internally calls the read callback function to obtain session data. PHP calls the open callback function before calling read.

The serialized string format returned by the read callback must be exactly the same as the format when the write callback saves data. PHP automatically deserializes the returned string and fills with the $_SESSION super global variable. Although the data looks very similar to the serialize() function, it should be noted that they are different. Please refer to: session.serialize_handler.

Write
The following signature callable callback is implemented:

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

The write callback function is called when the session saves data. This callback function takes as parameters the current session ID and the string after data serialization in $_SESSION. The process of serializing session data is completed by PHP based on the session.serialize_handler setting value.

The serialized data will be associated with the session ID for storage. When the read callback function is called to obtain data, the returned data must be completely consistent with the data passed into the write callback function.

PHP will call this callback function after the script is executed or the session_write_close() function is called. Note that after calling this callback function, the close callback function will be called internally in PHP.

Notice:

PHP will call the write callback function only after the output stream is written and closed, so the debugging information in the write callback function will not be output to the browser. If you need to use debug output in the write callback function, it is recommended to write debug output to a file.

destroy
The following signature callable callback is implemented:

 destroy(string $sessionId): bool

This callback function is called when the session_destroy() function is called, or the session_regenerate_id() function is called and the destroy parameter is set to true. This callback function operation returns true successfully, otherwise false.

gc
The following signature callable callback is implemented:

 gc(int $lifetime): bool

In order to clean up old data in the session, PHP will call the garbage collection callback function from time to time. The call cycle is controlled by the session.gc_probability and session.gc_divisor parameters. The lifetime parameter passed into this callback function is set by session.gc_maxlifetime. This callback function operation returns true successfully, otherwise false.

create_sid
The following signature callable callback is implemented:

 create_sid(): string

Execute this callback function when a new session ID is required. It will not pass in parameters when called, and its return value should be a string-formatted, valid session ID.

validate_sid
The following signature callable callback is implemented:

 validate_sid(string $key): bool

After opening session.use_strict_mode, this callback will be executed when a session is started, when the session ID is provided. The parameter key is the session ID to be verified. If the session of this ID already exists, it is a valid session ID. The return value should be true on success and false on failure.

update_timestamp
The following signature callable callback is implemented:

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

Execute this callback when updating session. The parameter key is the session ID; the parameter val is the session data. The return value should be true on success and false on failure.

Return value?
Returns true on success or false on failure.

Example?
Example #1 Custom session handler: See SessionHandlerInterface for the full code.

Only the call method is listed here. For the complete code, see SessionHandlerInterface.

Here the OOP prototype of the session_set_save_handler() function is used and the second parameter is used to register the shutdown function. This is recommended when registering an object as a session save handler.

 <?php class MySessionHandler implements SessionHandlerInterface { // 在这里实现接口} $handler = new MySessionHandler(); session_set_save_handler($handler, true); session_start(); // 现在可以使用$_SESSION 保存以及获取数据了

Comment Warning: Write and close callback functions will not be called after the object is destroyed. Therefore, objects cannot be used in these two callback functions, nor exceptions cannot be thrown. If an exception is thrown in a function, PHP will neither catch it nor track it, which will cause the program to terminate abnormally. But object destructors can use sessions.

The session_write_close() function can be called in the destructor to solve this problem. However, registering the shutdown callback function is a more reliable way to do it.

Warning If the session is closed after the script is finished, the current working directory may have been changed for some SAPIs. The session_write_close() function can be called to close the session before the script execution ends.