PHP — session_set_save_handler() Function
Sessions or session handling is a way to make the data available across various pages of a web application. The session_set_save_handler() function is used to set user-level session storage functions using which you can store and retrieve the data associated with the current session.
Syntax
session_cache_expire($sessionhandler [,$register_shutdown]);
Parameters
sessionhandler (Mandatory)
This is an object of the class that implements the interfaces SessionHandlerInterface and SessionIdInterface.
register_shutdown (Optional)
If you pass value for this parameter, the session_write_close() will be registered as a register_shutdown_function() function.
Return Values
This function returns a boolean value which is TRUE in case of success or FALSE in case of failure.
PHP Version
This function was first introduced in PHP Version 4 and works in all the later versions.
Example 1
Following example demonstrates the usage of the session_set_save_handler() function.
function close() < return(true); >function read($id) < global $session_path; $sess_file = "$session_path/sess_$id"; return (string) @file_get_contents($sess_file); >function write($id, $sess_data) < global $session_path; $sess_file = "$session_path/sess_$id"; if ($fp = @fopen($sess_file, "w")) < $return = fwrite($fp, $sess_data); fclose($fp); return $return; >else < return(false); >> function destroy($id) < global $session_path; $sess_file = "$session_path/sess_$id"; return(@unlink($sess_file)); >function gc($maxlifetime) < global $session_path; foreach (glob("$session_path/sess_*") as $filename) < if (filemtime($filename) + $maxlifetime < time()) < @unlink($filename); >> return true; > $res = session_set_save_handler("open", "close", "read", "write", "destroy", "gc"); if($res)< print("Successful"); >else < print("A problem occurred"); >session_start(); ?> One executing the above html file it will display the following message.
Session set save handler php
To implement database storage, or any other storage method, you will need to use session_set_save_handler() to create a set of user-level storage functions. A session handlers may be created using the SessionHandlerInterface or extending PHP’s internal handlers by inheriting from SessionHandler .
The callbacks specified in session_set_save_handler() are methods called by PHP during the life-cycle of a session: open , read , write and close and for the housekeeping tasks: destroy for deleting a session and gc for periodic garbage collection.
Therefore, PHP always requires session save handlers. The default is usually the internal ‘files’ save handler. A custom save handler can be set using session_set_save_handler() . Alternative internal save handlers are also provided by PHP extensions, such as sqlite , memcache and memcached and can be set with session.save_handler.
When the session starts, PHP will internally call the open handler followed by the read callback which should return an encoded string exactly as it was originally passed for storage. Once the read callback returns the encoded string, PHP will decode it and then populate the resulting array into the $_SESSION superglobal.
When PHP shuts down (or when session_write_close() is called), PHP will internally encode the $_SESSION superglobal and pass this along with the session ID to the write callback. After the write callback has finished, PHP will internally invoke the close callback handler.
When a session is specifically destroyed, PHP will call the destroy handler with the session ID.
PHP will call the gc callback from time to time to expire any session records according to the set max lifetime of a session. This routine should delete all records from persistent storage which were last accessed longer than the $lifetime .
session_set_save_handler
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
It is possible to register the following prototype:
session_set_save_handler ( object $sessionhandler , bool $register_shutdown = true ): bool
session_set_save_handler() sets the user-level session storage functions which are used for storing and retrieving data associated with a session. This is most useful when a storage method other than those supplied by PHP sessions is preferred, e.g. storing the session data in a local database.
Parameters
This function has two prototypes.
An instance of a class implementing SessionHandlerInterface , and optionally SessionIdInterface and/or SessionUpdateTimestampHandlerInterface , such as SessionHandler , to register as the session handler.
A callable with the following signature:
The open callback works like a constructor in classes and is executed when the session is being opened. It is the first callback function executed when the session is started automatically or manually with session_start() . Return value is true for success, false for failure.
A callable with the following signature:
The close callback works like a destructor in classes and is executed after the session write callback has been called. It is also invoked when session_write_close() is called. Return value should be true for success, false for failure.
A callable with the following signature:
The read callback must always return a session encoded (serialized) string, or an empty string if there is no data to read.
This callback is called internally by PHP when the session starts or when session_start() is called. Before this callback is invoked PHP will invoke the open callback.
The value this callback returns must be in exactly the same serialized format that was originally passed for storage to the write callback. The value returned will be unserialized automatically by PHP and used to populate the $_SESSION superglobal. While the data looks similar to serialize() please note it is a different format which is specified in the session.serialize_handler ini setting.
A callable with the following signature:
The write callback is called when the session needs to be saved and closed. This callback receives the current session ID a serialized version the $_SESSION superglobal. The serialization method used internally by PHP is specified in the session.serialize_handler ini setting.
The serialized session data passed to this callback should be stored against the passed session ID. When retrieving this data, the read callback must return the exact value that was originally passed to the write callback.
This callback is invoked when PHP shuts down or explicitly when session_write_close() is called. Note that after executing this function PHP will internally execute the close callback.
Note:
The «write» handler is not executed until after the output stream is closed. Thus, output from debugging statements in the «write» handler will never be seen in the browser. If debugging output is necessary, it is suggested that the debug output be written to a file instead.
A callable with the following signature:
This callback is executed when a session is destroyed with session_destroy() or with session_regenerate_id() with the destroy parameter set to true . Return value should be true for success, false for failure.
A callable with the following signature:
The garbage collector callback is invoked internally by PHP periodically in order to purge old session data. The frequency is controlled by session.gc_probability and session.gc_divisor. The value of lifetime which is passed to this callback can be set in session.gc_maxlifetime. Return value should be true for success, false for failure.
A callable with the following signature:
This callback is executed when a new session ID is required. No parameters are provided, and the return value should be a string that is a valid session ID for your handler.
A callable with the following signature:
This callback is executed when a session is to be started, a session ID is supplied and session.use_strict_mode is enabled. The key is the session ID to validate. A session ID is valid, if a session with that ID already exists. The return value should be true for success, false for failure.
A callable with the following signature:
This callback is executed when a session is updated. key is the session ID, val is the session data. The return value should be true for success, false for failure.
Return Values
Returns true on success or false on failure.
Examples
Example #1 Custom session handler: see full code in SessionHandlerInterface synopsis.
We just show the invocation here, the full example can be seen in the SessionHandlerInterface synopsis linked above.
Note we use the OOP prototype with session_set_save_handler() and register the shutdown function using the function’s parameter flag. This is generally advised when registering objects as session save handlers.
class MySessionHandler implements SessionHandlerInterface
// implement interfaces here
>
$handler = new MySessionHandler ();
session_set_save_handler ( $handler , true );
session_start ();
// proceed to set and retrieve values by key from $_SESSION
Notes
The write and close handlers are called after object destruction and therefore cannot use objects or throw exceptions. Exceptions are not able to be caught since will not be caught nor will any exception trace be displayed and the execution will just cease unexpectedly. The object destructors can however use sessions.
It is possible to call session_write_close() from the destructor to solve this chicken and egg problem but the most reliable way is to register the shutdown function as described above.
Current working directory is changed with some SAPIs if session is closed in the script termination. It is possible to close the session earlier with session_write_close() .
See Also
- The session.save_handler configuration directive
- The session.serialize_handler configuration directive.
- The register_shutdown_function() — Register a function for execution on shutdown
- The session_register_shutdown() — Session shutdown function
- Refer to » save_handler.inc for a full procedural reference implementation
- Session Functions
- session_abort
- session_cache_expire
- session_cache_limiter
- session_commit
- session_create_id
- session_decode
- session_destroy
- session_encode
- session_gc
- session_get_cookie_params
- session_id
- session_module_name
- session_name
- session_regenerate_id
- session_register_shutdown
- session_reset
- session_save_path
- session_set_cookie_params
- session_set_save_handler
- session_start
- session_status
- session_unset
- session_write_close