The Session Cache API is a super-simple two-function API for programmers to access small amounts of user-specific "state". Examples are the user's changing geographic location or a drop-down selection that is made upon first visit and needs to be remembered for the remainder of the session, or beyond, as in the Views Global Filter module.
The module comes in particularly handy when anonymous session data needs to be stored, which may not be viable using the standard $_SESSION way, due to constraints imposed by a caching engine or web accelerator like Varnish (in combination with a suitable page-exclusion strategy).

Being an API this module does NOT alter the behaviour of your site in any way unless its functions are called by other modules. So, if you are not a developer, then you may stop reading now. No need to use this module, unless another module tells you to.

While this module was designed to include the use-case of anonymous users and caching engines, it is itself NOT for caching pages, nodes, menus or large volumes of data. Nor should you use it to hold sensitive data like passwords, as there is no encryption. This module does one small job: help create a smooth experience for both users and programmers when it comes to anonymous as well as authenticated user session management.

The API is independent of the underlying session storage mechanism. In fact the storage model does not enter the API. Instead it is selected through the administrative UI (see screenshot) to best suit the deployed system configuration. The storage mechanisms available are:

cookie, i.e. store session on the user's computer
database, i.e. store session on the server, in a cache table
$_SESSION, i.e. store in server RAM, backed by core's {sessions} table
file, i.e. on the server, one small file per session (enable the Session Cache File submodule for this option, D7 only)

Administrators may switch the storage mechanism on the module's configuration page at any time.

The cookie, database and file storage mechanisms offer a seamless user experience across login/logout boundaries, that is: all user state is remembered after logout.
This is not the case for the $_SESSION option. The $_SESSION option may also be unsuitable when used in combination with a caching engine like Varnish. The cookie option can be a good solution. However you may have to combine it with a page exclusion strategy whereby no caching takes place for some pages, thus allowing for cookies to exist. Alternatively consider picking the IP address as the session identifier in combination with the database or file storage mechanisms.

The API to read and write user session data is the same in all cases and comprises these two functions:

  session_cache_set($bin, $data)
  session_cache_get($bin)

$data may be a number or string, an object, a multi-dimensional array etc. $bin is a string identifier you choose for the data you want to store for the current user. To guarantee uniqueness, you could prefix $bin with the name of the module that you use this API with. $data==NULL will result in the current user's section of the bin being deleted.

Cookies and database session caches created through this API expire after a UI-configurable number of hours or days. $_SESSIONs expire according to the global configuration -- see the comments in sites/default/files/default.settings.php. Or use Session Cookie Lifetime.

Programmers may add their own variations of the available storage mechanisms. See the README.

Modules known to use Session Cache API

Roadmap

Document some practical examples of the module in action in various Varnish and Boost contexts. For now see #2168375: How is this intended to integrate with Varnish? and #2281371: Using IP Geolocation Views & Maps with Boost module.

FAQ's

Q: What is the difference between this module and the Session API module?
A: Session API creates alternative session ids that remain valid after authenticated users log out and become anonymous. Session API does not implement any session data storage mechanisms, whereas that's what Session Cache API is all about. Session Cache API sessions also continue to live after logout, so you normally don't need Session API when you already use Session Cache API. See the README for more info on sessions, Session API and Session Cache API.

Q: How can I view the contents of my cookies?
Most browsers can reveal names, contents and expiry dates of the cookies on your machine. In Chrome for instance all you have to do is right-click your browser window and select Inspect element. This will bring up a panel and menu bar. In the menu bar click Resources. Then in the list on the left open the Cookies folder. You can also view what PHP believes your cookie contents are by logging in as an administrator and visiting admin/reports/status/php, scrolling almost to the bottom of the page, section "PHP variables".

RTBC issues for Session Cache API

Filters