Introducing WP_Session

Last time, I talked about what it would be like if WordPress supported sessions.  Well, I decided to put my money where my mouth is and actually took the time to build it.

I’m proud to announce the very first release of an implementation of [cci]WP_Session[/cci].

This new object implements PHP’s [cci]ArrayAccess[/cci] behind the scenes, so it functions almost exactly like the standard [cci]$_SESSION[/cci] object.  Just make a global reference to the object, then treat it like an associative array:


global $wp_session;

// A string
$wp_session['user_name'] = 'User Name';

// An array
$wp_session['user_contact'] = array( 'email' => '[email protected]' );

// An object
$wp_session['user_obj'] = new WP_User( 1 );

On the back end, the object stores its data in WordPress transients – one transient per user – each with a unique ID provided by WordPress’ [cci]PasswordHash[/cci] object to ensure uniqueness.  If you’ve got a caching plugin installed that uses memcached, then transients (like options) can be cached in memory, making the system very performant.

On the front end, your session token is stored in a cookie, called [cci]_wp_session[/cci].  WordPress will read this cookie, find your session, and populate the global object for you automatically.  At the end of its operation, WordPress will automatically write any changes to the session object back to the transient.

Since we’re aiming for as close to a 1:1 replacement for PHP’s standard session object as possible, version 1.0 of the class comes withe several WordPress-flavored helper functions:

  • [cci]wp_session_cache_expire()[/cci] – get the session expiration time
  • [cci]wp_session_commit()[/cci] – write session data out to the transient
  • [cci]wp_session_decode()[/cci] – load data into the session from a serialized string
  • [cci]wp_session_encode()[/cci] – write session data out to a serialized string
  • [cci]wp_session_regenerate_id()[/cci] – change the ID of the current session to a new, random one
  • [cci]wp_session_start()[/cci] – start the session and load data based on the user’s cookie
  • [cci]wp_session_status()[/cci] – check the status of the current session
  • [cci]wp_session_unset()[/cci] – clear out all variables in the current session
  • [cci]wp_session_write_close()[/cci] – write session data and end session.

To make life easier, [cci]wp_session_start()[/cci] is wired to the [cci]plugins_loaded[/cci] action hook to make sure your session data is available as early as possible.  Also, [cci]wp_session_write_close()[/cci] is wired to [cci]shutdown[/cci] to persist any changes to session data after all other functions have finished running.

Is is perfect? Probably not, but I’m comfortable enough with the class’ functionality to say it’s ready for a 1.0 release.  You can download the tagged ZIP from GitHub, or you can fork the project to work on it yourself.  If you have any recommendations, please submit a pull request so I can get them rolled in.

Remember, my ultimate goal is to get this class to be a part of WordPress core (hopefully in version 3.6).  So the more refinement we can get, the better!