(PHP 4, PHP 5, PHP 7)
session_set_save_handler — Sets user-level session storage functions
$open
, callable $close
, callable $read
, callable $write
, callable $destroy
, callable $gc
[, callable $create_sid
[, callable $validate_sid
[, callable $update_timestamp
]]] ) : boolSince PHP 5.4 it is possible to register the following prototype:
$sessionhandler
[, bool $register_shutdown = TRUE
] ) : boolsession_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.
This function has two prototypes.
sessionhandlerAn instance of a class implementing SessionHandlerInterface, SessionIdInterface, and/or SessionUpdateTimestampHandlerInterface, such as SessionHandler, to register as the session handler. Since PHP 5.4 only.
register_shutdownRegister session_write_close() as a register_shutdown_function() function.
open(string $savePath, string $sessionName)
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.
close()
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.
read(string $sessionId)
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.
write(string $sessionId, string $data)
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.
destroy($sessionId)
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.
gc($lifetime)
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.
create_sid()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.
Returns TRUE on success or FALSE on failure.
| Version | Description |
|---|---|
| 7.0.0 |
Added the optional validate_sid and
update_timestamp parameters.
|
| 5.5.1 |
Added the optional create_sid parameter.
|
| 5.4.0 | Added SessionHandlerInterface for implementing session handlers and SessionHandler to expose internal PHP session handlers. |
Example #1 Custom session handler: see full code in SessionHandlerInterface synopsis.
The following code is for PHP version 5.4.0 and above. 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.
<?php
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
Example #2 Custom session save handler using objects
The following code is for PHP versions less than 5.4.0.
The following example provides file based session storage similar to the
PHP sessions default save handler files. This
example could easily be extended to cover database storage using your
favorite PHP supported database engine.
Note we additionally register the shutdown function session_write_close() using register_shutdown_function() under PHP less than 5.4.0. This is generally advised when registering objects as session save handlers under PHP less than 5.4.0.
<?php
class FileSessionHandler
{
private $savePath;
function open($savePath, $sessionName)
{
$this->savePath = $savePath;
if (!is_dir($this->savePath)) {
mkdir($this->savePath, 0777);
}
return true;
}
function close()
{
return true;
}
function read($id)
{
return (string)@file_get_contents("$this->savePath/sess_$id");
}
function write($id, $data)
{
return file_put_contents("$this->savePath/sess_$id", $data) === false ? false : true;
}
function destroy($id)
{
$file = "$this->savePath/sess_$id";
if (file_exists($file)) {
unlink($file);
}
return true;
}
function gc($maxlifetime)
{
foreach (glob("$this->savePath/sess_*") as $file) {
if (filemtime($file) + $maxlifetime < time() && file_exists($file)) {
unlink($file);
}
}
return true;
}
}
$handler = new FileSessionHandler();
session_set_save_handler(
array($handler, 'open'),
array($handler, 'close'),
array($handler, 'read'),
array($handler, 'write'),
array($handler, 'destroy'),
array($handler, 'gc')
);
// the following prevents unexpected effects when using objects as save handlers
register_shutdown_function('session_write_close');
session_start();
// proceed to set and retrieve values by key from $_SESSION
When using objects as session save handlers, it is important to register the
shutdown function with PHP to avoid unexpected side-effects from the way
PHP internally destroys objects on shutdown and may prevent the
write and close from being called.
Typically you should register 'session_write_close' using the
register_shutdown_function() function.
As of PHP 5.4.0 you can use session_register_shutdown() or simply use the 'register shutdown' flag when invoking session_set_save_handler() using the OOP method and passing an instance that implements SessionHandlerInterface.
As of PHP 5.0.5 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().