phpman > perldoc > Apache::Session

NAME
    Apache::Session - A persistence framework for session data

SYNOPSIS
      use Apache::Session::MySQL;

      my %session;

      #make a fresh session for a first-time visitor
      tie %session, 'Apache::Session::MySQL';

      #stick some stuff in it
      $session{visa_number} = "1234 5678 9876 5432";

      #get the session id for later use
      my $id = $session{_session_id};

      #...time passes...

      #get the session data back out again during some other request
      my %session;
      tie %session, 'Apache::Session::MySQL', $id;

      validate($session{visa_number});

      #delete a session from the object store permanently
      tied(%session)->delete;

DESCRIPTION
    Apache::Session is a persistence framework which is particularly useful for tracking session
    data between httpd requests. Apache::Session is designed to work with Apache and mod_perl, but
    it should work under CGI and other web servers, and it also works outside of a web server
    altogether.

    Apache::Session consists of five components: the interface, the object store, the lock manager,
    the ID generator, and the serializer. The interface is defined in Session.pm, which is meant to
    be easily subclassed. The object store can be the filesystem, a Berkeley DB, a MySQL DB, an
    Oracle DB, a Postgres DB, Sybase, or Informix. Locking is done by lock files, semaphores, or the
    locking capabilities of the various databases. Serialization is done via Storable, and
    optionally ASCII-fied via MIME or pack(). ID numbers are generated via MD5. The reader is
    encouraged to extend these capabilities to meet his own requirements.

    A derived class of Apache::Session is used to tie together the three following components. The
    derived class inherits the interface from Apache::Session, and specifies which store and locker
    classes to use. Apache::Session::MySQL, for instance, uses the MySQL storage class and also the
    MySQL locking class. You can easily plug in your own object store or locker class.

INTERFACE
    The interface to Apache::Session is very simple: tie a hash to the desired class and use the
    hash as normal. The constructor takes two optional arguments. The first argument is the desired
    session ID number, or undef for a new session. The second argument is a hash of options that
    will be passed to the object store and locker classes.

  tieing the session
    Get a new session using DBI:

     tie %session, 'Apache::Session::MySQL', undef,
        { DataSource => 'dbi:mysql:sessions' };

    Restore an old session from the database:

     tie %session, 'Apache::Session::MySQL', $session_id,
        { DataSource => 'dbi:mysql:sessions' };

  Storing and retrieving data to and from the session
    Hey, how much easier could it get?

     $session{first_name} = "Chuck";
     $session{an_array_ref} = [ $one, $two, $three ];
     $session{an_object} = Some::Class->new;

  Reading the session ID
    The session ID is the only magic entry in the session object, but anything beginning with an "_"
    is considered reserved for future use.

     my $id = $session{_session_id};

  Permanently removing the session from storage
     tied(%session)->delete;

BEHAVIOR
    Apache::Session tries to behave the way the author believes that you would expect. When you
    create a new session, Session immediately saves the session to the data store, or calls die() if
    it cannot. It also obtains an exclusive lock on the session object. If you retrieve an existing
    session, Session immediately restores the object from storage, or calls die() in case of an
    error. Session also obtains a non-exclusive lock on the session.

    As you put data into the session hash, Session squirrels it away for later use. When you untie()
    the session hash, or it passes out of scope, Session checks to see if anything has changed. If
    so, Session gains an exclusive lock and writes the session to the data store. It then releases
    any locks it has acquired.

    Note that Apache::Session does only a shallow check to see if anything has changed. If nothing
    changes in the top level tied hash, the data will not be updated in the backing store. You are
    encouraged to timestamp the session hash so that it is sure to be updated.

    When you call the delete() method on the session object, the object is immediately removed from
    the object store, if possible.

    When Session encounters an error, it calls die(). You will probably want to wrap your session
    logic in an eval block to trap these errors.

LOCKING AND TRANSACTIONS
    By default, most Apache::Session implementations only do locking to prevent data corruption. The
    locking scheme does not provide transactional consistency, such as you might get from a
    relational database. If you desire transactional consistency, you must provide the Transaction
    argument with a true value when you tie the session hash. For example:

     tie %s, 'Apache::Session::File', $id {
        Directory     => '/tmp/sessions',
        LockDirectory => '/var/lock/sessions',
        Transaction   => 1
     };

    Note that the Transaction argument has no practical effect on the MySQL and Postgres
    implementations. The MySQL implementation only supports exclusive locking, and the Postgres
    implementation uses the transaction features of that database.

IMPLEMENTATION
    The way you implement Apache::Session depends on what you are trying to accomplish. Here are
    some hints on which classes to use in what situations

STRATEGIES
    Apache::Session is mainly designed to track user session between http requests. However, it can
    also be used for any situation where data persistence is desirable. For example, it could be
    used to share global data between your httpd processes. The following examples are short
    mod_perl programs which demonstrate some session handling basics.

  Sharing data between Apache processes
    When you share data between Apache processes, you need to decide on a session ID number ahead of
    time and make sure that an object with that ID number is in your object store before starting
    your Apache. How you accomplish that is your own business. I use the session ID "1". Here is a
    short program in which we use Apache::Session to store out database access information.

     use Apache;
     use Apache::Session::File;
     use DBI;

     use strict;

     my %global_data;

     eval {
         tie %global_data, 'Apache::Session::File', 1,
            {Directory => '/tmp/sessiondata'};
     };
     if ($@) {
        die "Global data is not accessible: $@";
     }

     my $dbh = DBI->connect($global_data{datasource},
        $global_data{username}, $global_data{password}) || die $DBI::errstr;

     undef %global_data;

     #program continues...

    As shown in this example, you should undef or untie your session hash as soon as you are done
    with it. This will free up any locks associated with your process.

  Tracking users with cookies
    The choice of whether to use cookies or path info to track user IDs is a rather religious topic
    among Apache users. This example uses cookies. The implementation of a path info system is left
    as an exercise for the reader.

    Note that Apache::Session::Generate::ModUsertrack uses Apache's mod_usertrack cookies to
    generate and maintain session IDs.

     use Apache::Session::MySQL;
     use Apache;

     use strict;

     #read in the cookie if this is an old session

     my $r = Apache->request;
     my $cookie = $r->header_in('Cookie');
     $cookie =~ s/SESSION_ID=(\w*)/$1/;

     #create a session object based on the cookie we got from the browser,
     #or a new session if we got no cookie

     my %session;
     tie %session, 'Apache::Session::MySQL', $cookie, {
          DataSource => 'dbi:mysql:sessions', #these arguments are
          UserName   => 'mySQL_user',         #required when using
          Password   => 'password',           #MySQL.pm
          LockDataSource => 'dbi:mysql:sessions',
          LockUserName   => 'mySQL_user',
          LockPassword   => 'password'
     };

     #Might be a new session, so lets give them their cookie back

     my $session_cookie = "SESSION_ID=$session{_session_id};";
     $r->header_out("Set-Cookie" => $session_cookie);

     #program continues...

SEE ALSO
    Apache::Session::MySQL, Apache::Session::Postgres, Apache::Session::File,
    Apache::Session::DB_File, Apache::Session::Oracle, Apache::Session::Sybase

    The O Reilly book "Apache Modules in Perl and C", by Doug MacEachern and Lincoln Stein, has a
    chapter on keeping state.

    CGI::Session uses OO interface to do same thing. It is better maintained, but less possibilies.

    Catalyst::Plugin::Session - support of sessions in Catalyst

    Session - OO interface to Apache::Session

LICENSE
    Under the same terms as Perl itself.

AUTHORS
    Alexandr Ciornii, <http://chorny.net> - current maintainer

    Jeffrey Baker <jwbaker AT acm.org> is the author of Apache::Session.

    Tatsuhiko Miyagawa <miyagawa AT bulknews.net> is the author of Generate::ModUniqueID and
    Generate::ModUsertrack

    Erik Rantapaa <rantapaa AT fanbuzz.com> found errors in both Lock::File and Store::File

    Bart Schaefer <schaefer AT zanshin.com> notified me of a bug in Lock::File.

    Chris Winters <cwinters AT intes.net> contributed the Sybase code.

    Michael Schout <mschout AT gkg.net> fixed a commit policy bug in 1.51.

    Andreas J. Koenig <andreas.koenig AT anima.de> contributed valuable CPAN advice and also
    Apache::Session::Tree and Apache::Session::Counted.

    Gerald Richter <richter AT ecos.de> had the idea for a tied hash interface and provided the initial
    code for it. He also uses Apache::Session in his Embperl module and is the author of
    Apache::Session::Embperl

    Jochen Wiedmann <joe AT ipsoft.de> contributed patches for bugs and improved performance.

    Steve Shreeve <shreeve AT uci.edu> squashed a bug in 0.99.0 whereby a cleared hash or deleted key
    failed to set the modified bit.

    Peter Kaas <Peter.Kaas AT lunatech.com> sent quite a bit of feedback with ideas for interface
    improvements.

    Randy Harmon <rjharmon AT uptimecomputers.com> contributed the original storage-independent object
    interface with input from:

      Bavo De Ridder <bavo AT ace.be>
      Jules Bean <jmlb2 AT hermes.uk>
      Lincoln Stein <lstein AT cshl.org>

    Jamie LeTaul <jletual AT kmtechnologies.com> fixed file locking on Windows.

    Scott McWhirter <scott AT surreytech.uk> contributed verbose error messages for file locking.

    Corris Randall <corris AT line6.net> gave us the option to use any table name in the MySQL store.

    Oliver Maul <oliver.maul AT ixos.de> updated the Sybase modules

    Innumerable users sent a patch for the reversed file age test in the file locking module.

    Langen Mike <mike.langen AT tamedia.ch> contributed Informix modules.