Update Oct 17th, 2015: Warning: this module is not supported by Acquia and some other hosting companies because it can tax the file system and/or conflict with Varnish.
"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 anonymoussession 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 likeVarnish.
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 Drupal programmer, 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. Both the cookie and database 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 which may also be unsuitable when used in combination with a caching engine like Varnish. The cookie option is therefore often a good solution, also because it distributes storage foot print from the server to its clients.
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 theREADME.
Modules known to use Session Cache API
Roadmap
The module does one well-defined task. Few bells and whistles to add. Would like to document some practical examples of the module in action in various Varnish contexts.
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"."