PHP —

Building User-Defined Session Handlers

When the PHP session.save_handler parameter is set to user, PHP expects to find functions that provide the low-level session management support. These are the functions the developer needs to write. The functions must conform to the defined prototypes:

Boolean open(string save_path, string session_name)

Called by PHP when session_start( ) or session_register( ) is called to access the session store. PHP passes the php.ini parameters session.save_path and session.name as arguments to this function, and these arguments are used to locate the session store. By default, session.save_path is set to /tmp to indicate the directory for the files storage method, and session.name is set to PHPSESSID as the name of the session ID cookie. These parameters select the database and table used to store session variables.

Boolean close( )

Called by PHP at the end of a script when a session is closed. The function should return false if an error occurs during the close operation and true on success.

mixed read(string session_id)

Called by PHP to read the variables for the session identified by session_id when a session is initialized. The function returns a string that contains the serialized session variables. The PHP engine converts the string to the individual session variables and sets up the $HTTP_SESSION_VARS array. If no session is found, the function should return a blank string. The function should return false if an error occurs during the read operation and true on success.

Boolean write(string session_id, string values)

This function is called by PHP when session variables are updated and when a session is initialized. This function is passed the ID of the session, and the session variables serialized into a single string by PHP. The implementation of write( ) must store the serialized string associated with the session, and record the time the session was last accessed. The serialized string stored for the session is returned by the read( ) handler. PHP uses this function not only to update session variables but to record the last access time when a session is initialized. The function should return false if an error occurs during the write operation and true on success.

Boolean destroy(string session_id)

Called by PHP when the session identified by session_id is destroyed. Removes storage dedicated to the identified session. The function should return false if an error occurs during the destroy operation and true on success.

Boolean gc(int max_lifetime)

Called by PHP with a probability set by session.gc_probability when a session is initialized. Removes the data and variables stored by dormant sessions. The value of session.gc_maxlifetime is passed to this function and is used to determine which are idle sessions. If the garbage collection handler is executed without error, it should return true.

While the return types and the parameters passed to the functions must conform to the prototypes listed here, the actual function names can be different. These functions need to be registered with PHP using session_set_save_handler( ):

session_set_save_handler(string open, string close, string read, string write, string destroy, string gc)

Registers a set of PHP function names as the callback functions for user-defined session management. The arguments to this function are the names of the functions. The six parameters passed to session_set_save_handler( ) are interpreted as the names of the open, close, read, write, destroy, and gc functions.

Once registered, PHP uses these handler functions when the PHP session management calls are made. The handler functions aren't called directly by scripts that use session management. More detail about these handlers is given later when we describe the MySQL storage implementations.