Apache-SessionManager

 view release on metacpan or  search on metacpan

SessionManager/cookpod.pod  view on Meta::CPAN

=pod

=head1 NAME

Apache::SessionManager::cookpod - Session management Cookpod with
Apache::SessionManager

=head1 INTRODUCTION

This HOWTO describes use of L<Apache::SessionManager|Apache::SessionManager>
with several application servers  and toolkits available designed to run (also)
under mod_perl. There are many ways to do it; this document will not describe
all possible configurations.

=head1 WHAT DOES Apache::SessionManager DO

L<Apache::SessionManager|Apache::SessionManager> is a HTTP session manager
wrapper around L<Apache::Session|Apache::Session>
(L<Apache::Session|Apache::Session> provides a persistence mechanism for data
associated with a session  between a client and the server).

L<Apache::SessionManager|Apache::SessionManager> allows you to integrate a
transparent session management into your web application (it handles for you
the cookie/URI session tracking management).

A session is a set of interactions (HTTP transactions).  For example, a visitor
may add items to be purchased to a shopping cart and the  contents of the cart
may be made visible by several different pages the visitor views  during the
purchase process.

=head1 Apache::SessionManager WITH CGI::Application

=head2 INTRODUCTION

This section describes how to use
L<Apache::SessionManager|Apache::SessionManager> within
L<CGI::Application|CGI::Application>. The idea is to use sublass
L<CGI::Application|CGI::Application> by adding session support and to use 
CGI::Application::SessionManager as base class for your applications.

L<CGI::Application|CGI::Application> is intended to make it easier to create
sophisticated,  reusable web-based applications.  

L<CGI::Application|CGI::Application> is an Object-Oriented Perl module which
implements an Abstract Class. It is not intended that this package be
instantiated directly. Instead, it is intended that your Application Module
will be  implemented as a Sub-Class of L<CGI::Application|CGI::Application>.

=head2 CONFIGURATION

This section illustrates how to use configure
L<Apache::SessionManager|Apache::SessionManager> for use within
L<CGI::Application|CGI::Application> Perl extension.

=head3 CONFIGURATION VIA F<httpd.conf>

In F<httpd.conf> (or any files included by the C<Include> directive):

   <IfModule mod_perl.c>

      PerlModule Apache::SessionManager
      PerlTransHandler Apache::SessionManager

      Alias /cgi-application "/usr/local/apache/cgi-application"
      <Location /cgi-application>
         SetHandler perl-script
         PerlHandler Apache::Registry
         PerlSendHeader On
         PerlSetupEnv   On
         Options ExecCGI

         PerlSetVar SessionManagerTracking On
         PerlSetVar SessionManagerExpire 90
         PerlSetVar SessionManagerInactivity 900
         PerlSetVar SessionManagerName CGIAPPSESSIONID
         PerlSetVar SessionManagerStore File
         PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data/cgiapp"
         PerlSetVar SessionManagerDebug 5
      </Location>   

   </IfModule>   

=head3 CONFIGURATION VIA F<.htaccess>

SessionManager/cookpod.pod  view on Meta::CPAN

students on a departmental Web server at a university

=item *

individual customers of an ISP

=item *

clients of a Web-hosting company. 

=back

This chapter will helps you to use
L<Apache::SessionManager|Apache::SessionManager> in one of this situation.

=head2 REQUIREMENTS

There are some prerequisites in order to install and use
L<Apache::SessionManager|Apache::SessionManager> without C<root> privileges:

=over 4

=item * a shell

Obvious

=item * gcc

C<gcc> is necessary in order to compile some required module like
L<Storable|Storable> or L<Digest::MD5|Digest::MD5> that have several XS code

=item * make

Again, obvious

=item * mod_perl with hook C<PERL_HEADER_PARSER=1>

You can use this simple script (supplied in 'Practical mod_perl' book) to see
enabled hooks:

   use mod_perl_hooks;

   for my $hook(mod_perl::hooks()) {
      if (mod_perl::hooks($hook)) {
         print "$hook is enabled\n";
      }
      else {
         print "$hook is not enabled\n";
      }
   }  

=item * a configurable F<.htaccess> file

I know, you could install and run another C<httpd> instance on a port greather
than 1024 and configure directly your F<httpd.conf>. Then you could ask to your
Webmaster in order to proxy your Apache from main web server (at port 80), if
you dont want export to the world a web site in a port different than 80.

So, working with F<.htaccess> files is the only possibilty to enable and
configure session manager transparently (both for web users and  your
sysadmin).

Depending on wich Apache directives you would override, first you must check
the status of C<AllowOverride> directive for your directories.

If none of C<AllowOverride> directive appears in main F<httpd.conf> then you
can use all allowed directives in F<.htaccess> file (by default 
C<AllowOverride> is set to C<All>, that means that any directive which has the
F<.htaccess> C<Context> is allowed in F<.htaccess> files).

Otherwise, be sure that at least the directive like:

   AllowOverride FileInfo

is present in order to use C<SetHandler> in F<.htaccess> file.

You can found more info about allowed directives at
http://httpd.apache.org/docs/mod/core.html#allowoverride

For example, if you want to run CGI scripts also outside F<cgi-bin> script
directory, then a directive like:

   AllowOverride FileInfo Options

should be appear in order to override directory behaviour by adding a:

   Options +ExecCGI

in your F<.htaccess> file.

=item * lwp || ftp || ...

A way to transfer the perl packages in the system :-)

=back

=head2 CREATING YOU PRIVATE PERL LIBRARY DIRECTORY

First of all, you must choose and create the directory that will contain the
private installation copy of Perl modules. It should be readable by web server.

   %> mkdir /path/to/your/perl-lib

=head2 INSTALLING Storable

As L<Apache::Session|Apache::Session> documentation says, "no particular 
modules are required, but most of L<Apache::Session's|Apache::Session>
functions require L<Digest::MD5|Digest::MD5> and L<Storable|Storable>". 

Here, we explain how to install L<Storable|Storable> if it isn't already
present in the machine. Note that starting from Perl 5.8.0,
L<Storable|Storable> is a core module.

   %> lwp-download http://search.cpan.org/CPAN/authors/id/A/AM/AMS/Storable-2.07.tar.gz 
   %> tar -xzvf Storable-2.07.tar.gz  
   %> cd Storable-2.07   
   %> perl Makefile.PL PREFIX=/path/to/your/perl-lib
   %> make
   %> make test
   %> make install

SessionManager/cookpod.pod  view on Meta::CPAN

         use lib '/path/to/your/perl-lib/lib/site_perl',
                 '/path/to/your/perl-lib/lib/';           # for Storable.pm
      </Perl>
      PerlModule Apache::SessionManager
      <FilesMatch "\.cgi$">
         SetHandler perl-script
         PerlHandler Apache::Registry
         PerlSendHeader On
         PerlSetupEnv On
         Options ExecCGI
         PerlHeaderParserHandler Apache::SessionManager

         PerlSetVar SessionManagerTracking On
         PerlSetVar SessionManagerExpire 300
         PerlSetVar SessionManagerInactivity 1800
         PerlSetVar SessionManagerName SESSIONID
         PerlSetVar SessionManagerStore File
         PerlSetVar SessionManagerStoreArgs "Directory => /path/to/session/data"
         PerlSetVar SessionManagerDebug 5
      </FilesMatch>
   </IfModule>   

To test session you can use this simple CGI script:

   #!/usr/bin/perl

   use Data::Dumper ();

   my $session = Apache::SessionManager::get_session(Apache->request);
   $session->{$$ . '-' . rand()} = rand; 

   print "Content-type: text/html\n\n";
   print '<PRE>' . Data::Dumper::Dumper($session) . '</PRE>'; 

Save it with a F<.cgi> extension (like F<session.cgi>) in the same directory
where you have F<.htaccess> and make it executable by web server.

=head1 USING Apache::SessionManager AND Apache::DBI 

=head2 INTRODUCTION

This section describes how to use
L<Apache::SessionManager|Apache::SessionManager> with
L<Apache::DBI|Apache::DBI> when using a RDBMS for sessions back-end datastore.

L<Apache::DBI|Apache::DBI> is a useful mod_perl module that caches database
connections according to args (like DBD driver, user, password) and attributes.
So, if your application uses a different user and/or attributes to connect to a
(different) database, every connection will be cached. Also, every child could
have these cached DB's handles. L<Apache::DBI|Apache::DBI> works very well for
web applications that uses same DB user.

=head2 CONFIGURATION

There is no need of extra configuration steps to use advantage of persistent DB
connections offered by L<Apache::DBI|Apache::DBI> when using
L<Apache::SessionManager|Apache::SessionManager> with a RDBMS as session
datastore.

L<Apache::DBI|Apache::DBI> overrides DBI C<connect> and C<disconnect>  methods
and it intercepts, transparently, all related calls (including
L<Apache::SessionManager|Apache::SessionManager> DBI calls) by returning cached
connections, if any. 

Simply add a line like:

   PerlModule Apache::DBI

in your F<httpd.conf>, or:

   use Apache::DBI;

in a F<startup.pl> file where you can also setup your initial persistent
connection.

However, remember that you must load L<Apache::DBI|Apache::DBI> module before
L<DBI|DBI> or any module that uses it! 

=head2 TESTING

Restart the server and... test your application :-)

Additionally, you can enable perl-status console by putting, before loading
L<Apache::DBI|Apache::DBI>, lines like:

   <Location /perl-status>
      SetHandler perl-script
      PerlHandler Apache::Status
      # or PerlResponseHandler Apache::Status in mod_perl 2
   </Location>   

You will see in the 'DBI connections' page, the cached datasource (in current
child) used by Apache::Session::* plugin datastore you've chosen.  Also yo can
start C<httpd> in single mode with C<-X> option to work with a single child.

=head2 SEE ALSO

L<Apache::DBI|Apache::DBI>

=head1 MOVING SESSION EXPIRATION POLICIES TO THE CLIENT SIDE

=head2 INTRODUCTION

This section describes how to move expiration policies on the client side by
setting expiration cookie properties appropriately.

=head2 CONFIGURATION

Practically, you must only add C<Expires> cookie attribute in
C<SessionManagerCookieArgs> module directive:

   <Location /sessions>
      SetHandler perl-script
      PerlHandler Apache::MyModule

      PerlSetVar SessionManagerExpire none
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerCookieArgs "Path => /sessions, Expires => +2d"
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp"
   </Location>