NAME

CGI::Session::Driver::memcache - Store CGI::Session objects in memcache daemon

SYNOPSIS

  my $memd = new Cache::Memcached({
    servers => ['localhost:11211'],
  });
  if (!$memd) {die("No Connection to Memcached !");}

  my $cgi = CGI->new();
  my $sess = CGI::Session->new("driver:memcache", $cgi, {'Handle' => $memd});

  # Get and Set the standard CGI::Session way
  # Get
  my $v = $sess->param('greet_en');
  # Set
  $sess->param('greet_en', "Hi !");

DESCRIPTION

CGI::Session::Driver::memcache is a storage driver (only referred as 'driver' in CGI::Session lingo) for persisting CGI Sessions into a fast memcached server.

It requires you to instantiate memcached connection using any of the available Perl memcache client libraries and pass it to CGI::Session constructor along with "DSN" "driver:memcache" (see SYNOPSIS).

You do not need to learn any of CGI::Session::Driver::memcache, but only use it as a driver. All your learning efforts should go to CGI::Session (see also CGI::Session::Tutorial). Only learning related to this driver is how to create a connection (see $memd above) using one of the Perl Memcached client modules and passing it to CGI::Session constructor.

METHODS

Not applicable to CGI::Session API user. CGI::Session::Driver::memcache implements methods required by CGI::Session::Driver (interface). Note that CGI::Session::Driver method 'traverse' (accessible via CGI::Session->find()) is not supported currently (partially because Perl APIs do not support iterating the keys of cache).

Why CGI::Session::Driver::memcache ?

While it is possible to use memcache client directly to store sessions into memcache server, the CGI::Session provides a nice modular abstraction with a lot of thought put into it. Developing session management directly against memcached makes setting up a memcache server a hard dependency for the app. By using CGI::Session in between the app and session storage backend it is easy to "right-size" storage backend according to requirements of current project.

Setting up Memcached Server

See README in the package for short tutorials on setting up the memcached server and testing the installation from command line.

BUGS

This driver requires Memcached connection handle to be passed to CGI::Session constructor as "raw" connection handle ({'Handle' => $memd}), making caller responsible for passing a valid connection. This is actually good for relieving CGI::Session from the intricacies of suppporting various Memcached client modules with differences in constructions (the rest of the main API on these module is generally very similar).

This driver and CGI::Session underpinnings do very little to ensure the server is actually alive. The situation is even worse for Memcached client modules that return valid client instance without server running (This is very different from lot of other DB Modules like DBI/DBD* or Net::LDAP, where any problems with server raises exceptions or returns undefined handles). Make sure your server is alive by either Calling stats() on Memcached client:

   my $stats = $memd->stats(); # Allows: [$keys]
   if (ref($stats) || !$stats->{'total'}) {die("No stats from Memcached - Memcached not running ?");}

... or by doing a set/get test sequence:

   my $testval = "it_is_".time();
   my $ok = $memd->set("whatstime", $testval);
   if (!$ok) {die("Setting k-v in memcached failed - Memcached not running ?");}
   # Optional get to double verify reading back
   my $itis_t = $memd->get("whatstime") || '';
   if (!$itis_t) {die("Value stored to Memcached earlier could not be read back !");}

SEE ALSO

CGI::Session, CGI::Session::Tutorial, Cache::Memcached::libmemcached for excellent list of Perl memcache client APIs (links to the module can be found there).

See memcached website (http://memcached.org/) for more information on memcache deamon.

CREDITS

Creators of CGI::Session for a great modular web session API.

AUTHOR and COPYRIGHT

Copyright (c) 2010-2013 Olli Hollmen <olli.hollmen@gmail.com>. All rights reserved. This library is free software. You can modify and or distribute it under the same terms as Perl itself.