F.2 PHP Session Management

In Chapter 10, we described the three characteristics of session management: storing session variables, matching these session variables to HTTP requests using a session identifier, and removing timed-out sessions with garbage collection. PHP session management largely takes care of these issues, and with the default configuration, you needn't worry how storage, session identification, and garbage collection are performed.

To understand what we accomplish in this appendix, you should know a bit about what PHP does behind the scenes. You should also understand the layers within the PHP session support and how you can hook your own functions in.

Figure F-2 shows how session variables are stored and retrieved when PHP runs an application script that uses session support. PHP session support is divided into two layers: the PHP session management layer provides the interface to session-based scripts, and the storage layer is responsible for reading and writing session variables in the session store. The storage layer in the default configuration works with files in a directory designated for PHP session storage.

Figure F-2. PHP session management

When a script makes a call to session_start( ), the PHP session management layer reads the session ID from the HTTP request, starts a session by making open and read calls to the storage layer, and initializes the session variables in the $_SESSION array. The open call is responsible for opening the session store: the default implementation simply identifies the directory that stores the session file. The read call is responsible for finding and returning the serialized session variables associated with the session ID; we discuss serialization later in this section.

When the script ends, the session management layer calls write and close functions to write the contents of the array $_SESSION back to the session store and close the session. The write function is responsible for finding the session file and writing the serialized session variables to that file. The close function formally closes the session store: in the default implementation, the close operation does nothing, as no close operation is required on a file system.

The session management layer is responsible for serializing and deserializing the session variables. Serialization means that the variables are converted to strings that describe the variable name, its type, length, and value. When a script ends, the session variables in the array $_SESSION are serialized and passed as a single string to the write function to be saved in the session store. For example, if the array $_SESSION contains a string variable name, a float variable height, and an integer variable age; the serialized string might look like this:


When the read function identifies a session file, it simply returns the serialized string back to the session management layer to be deserialized into the $_SESSION array.

The PHP session storage layer also implements functions that destroy a session when a script calls session_destroy( ). It also performs garbage collection to remove timed-out sessions. Unlike the other storage functions, garbage collection is not tied directly to an event in the application script. Instead the session management layer calls garbage collection randomly when a call is made to session_start( ). The probability that garbage collection is called is defined by the configuration parameters session.gc_probability and session.gc_dividend. For a more detailed discussion about garbage collection see Chapter 10.

F.2.1 PHP Session Management Storage Methods

Different storage strategies can be used for session management. PHP can be configured to store session variables in files on disk (the default method), in memory, or in a user-defined way. The storage method used is configured by the session.save_handler parameter in the php.ini file. The values the session.save_handler parameter can take are:


This is the default storage method for PHP, where session variables are serialized and written to a session disk file.


The memory management storage method allows session variables to be stored in Apache's runtime memory. Using memory has the advantage of better performance than files on disk. However, if many sessions must be supported, and each session uses a large volume of data, the memory used by the Apache process may be high. To use memory to store session variables, PHP must be configured and compiled to use an installed memory management module (--with-mm). The memory management module is not available for Microsoft Windows systems.


The user-defined method allows an application to save session variables to systems other than file or memory, such as to a table in a database. By defining several handler prototypes, PHP allows the developer to define the behavior of the low-level session storage. A full explanation is given in the next section.

F.2.2 Building User-Defined Storage Handlers

By implementing user-defined storage handlers, a developer can modify how PHP sessions are stored without needing to change any application logic. The only modification required in a PHP script is an additional require directive that specifies the use of the user-defined session management handlers.

When the PHP session.save_handler parameter is set to user, you are basically writing your own replacement for the right-hand side of Figure F-2 shown earlier. Everything from the column showing the open through close calls to the Session Store is up to you. PHP must be provided with a set of functions that provide the low-level session storage support. These functions replace the default storage layer illustrated in Figure F-2. The functions that you need to write, and the prototypes they must conform to, are listed below:

Boolean open(string save_path, string session_name)

Called by PHP to open the session store when a script calls session_start( ). PHP passes the values of the parameters session.save_path and session.name defined in php.ini as arguments to this function, and these arguments can be 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. The function should return true on success and false on failure.

Later, when we implement the handlers to store session variables in a MySQL database, we use these parameters to select a database and a table.

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 session management converts the string to the individual session variables and sets up the $_SESSION 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.

Boolean write(string session_id, string values)

Called by PHP at the end of a script to save the session variables managed in the $_SESSION array to the session store. 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 function should return false if an error occurs during the write operation and true on success.

Boolean close( )

Called by PHP at the end of a script and can be used to perform tasks required to close the session store. The function should return false if an error occurs during the close operation and true on success.

Boolean destroy(string session_id)

Called by PHP when a script calls session_destroy( ). The function should use the session_id parameter to identified a session and remove the associated storage. The function should return false if an error occurs during the destroy operation and true on success.

Boolean gc(int max_lifetime)

The garbage collection function called by PHP to identify and remove sessions that have not been accessed within max_lifetime seconds. The value of the max_lifetime parameter is the value of session.gc_maxlifetime defined in php.ini. When a script calls session_start( ), PHP randomly calls the garbage collection function with a probability defined by the parameters session.gc_probability and session.gc_dividend. If the garbage collection handler is executed without error, it should return true, and false otherwise. For a more detailed discussion about garbage collection see Chapter 10.

The return types and the parameters passed to the functions must conform to the prototypes listed here, but you can set the actual function names to whatever you like. However, these functions need to be registered with PHP using session_set_save_handler( ) :

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

Registers PHP function names as the handler 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 described previously in this section.