=pod =head1 NAME Apache::SessionManager::cookpod - Session management Cookpod with Apache::SessionManager =head1 INTRODUCTION This HOWTO describes use of L 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 is a HTTP session manager wrapper around L (L provides a persistence mechanism for data associated with a session between a client and the server). L 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 within L. The idea is to use sublass L by adding session support and to use CGI::Application::SessionManager as base class for your applications. L is intended to make it easier to create sophisticated, reusable web-based applications. L 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. =head2 CONFIGURATION This section illustrates how to use configure L for use within L Perl extension. =head3 CONFIGURATION VIA F In F (or any files included by the C directive): PerlModule Apache::SessionManager PerlTransHandler Apache::SessionManager Alias /cgi-application "/usr/local/apache/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 =head3 CONFIGURATION VIA F<.htaccess> In the case you don't have access to F, you can put similar directives directly into an F<.htaccess> file: SetHandler perl-script PerlHandler Apache::Registry PerlSendHeader On PerlSetupEnv On Options ExecCGI PerlHeaderParserHandler Apache::SessionManager 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 The only difference is that you cannot use C directive (I used C) and you must install L in C
phase of Apache request instead of C phase. =head3 NOTES ON USING F<.htaccess> INSTEAD OF F =over 4 =item * In this cases it is necessary to install L in C
phase and not into C phase (in this phase, F<.htaccess> hasn't yet been processed). =item * Using F<.htaccess>, it is possible to use only cookies for the session tracking. =back =head2 SUBCLASSING CGI::Application We subclass L in order to supply the C method where we restore the session object from datastore and put it into class property: package CGI::Application::SessionManager; use Apache::SessionManager; use base 'CGI::Application'; sub cgiapp_init { my $self = shift; # if mod_perl $self->{'session'} = Apache::SessionManager::get_session(Apache->request) if $ENV{MOD_PERL}; } Save it under the directory F. The reason to for subclassing this is the benefits is creating a custom "application super-class" from which which all your CGI applications would inherit, instead of L. Then we write F Application Module that inherit from our super-class CGI::Application::SessionManager: package WebApp; use Data::Dumper; use base 'CGI::Application::SessionManager'; sub setup { my $self = shift; $self->start_mode('mode1'); $self->mode_param('rm'); $self->run_modes( 'mode1' => 'do_session' 'mode2' => 'do_stuff', 'mode3' => 'do_more_stuff', 'mode4' => 'do_something_else', ); } sub do_session { $self = shift; $self->{'session'}->{rand()} = rand; my $out = '
' . Dumper($self->{'session'}) . '
';
        return $out;
   }
   sub do_stuff { return $_[0]->get_current_runmode() }
   sub do_more_stuff { return $_[0]->get_current_runmode() }
   sub do_something_else { print $_[0]->get_current_runmode() }
   1; 

Save it as F.

=head2 TESTING Apache::SessionManager

To test our application we must implement the Instance Script that is what is
actually  called by your web server.

It is a very small, simple file which simply creates an instance of your
application and calls an inherited method, B. Following is the entirety
of F:

   #!/usr/local/bin/perl
   use WebApp;

   my $webapp = WebApp->new();
   $webapp->run();  

Restart the httpd server and launch http://localhost/cgi-application/webapp.cgi

=head2 SEE ALSO

L,
L, L, perl

=head1 Apache::SessionManager WITH CGI::Builder

=head2 INTRODUCTION

This section describes how to use
L with
L toolkit.

L is a set of Perl modules which collectively implement a
template processing system. In this context, a template is a text document
containing special markup tags.

The idea is to use the
L extension
(available on CPAN), that is the L wrapper around
L.

For installation and use of this extension, please see
L documentation.

=head2 SEE ALSO

L,
L,
L, L, perl

=head1 Apache::SessionManager WITH HTML::Mason

=head2 INTRODUCTION

This section describes use of L
with L (L).  There are many
ways to do it; this document will not describe all possible configurations.
It's meant to be a quick C HOWTO and also to answer some
common questions that appear on the mailing list.

Yes. I know, there's
L. But I
wrote and released L some time
before L
has been released. And since I need session object also outside Response
phase (like Authentication and/or Authorization phases) I still use
L with Mason.

=head2 CONFIGURATION

The idea is to use a global variable C<$session> in order to store session
object, and to initialize it into autohandler special component instead of call
a separate  component in each Mason page.

L can be configured under mod_perl in two different
ways: 

=head3 CONFIGURATION VIA CUSTOM CODE

This method is preferred because gives you complete control over how
L handles requests  at the cost of a bit of extra code
to maintain.

In F:

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager
   PerlRequire /usr/local/apache/conf/masonhandler.pl

   Alias /mason "/usr/local/apache/htdocs/mason"
   
      SetHandler perl-script
      PerlHandler HTML::Mason

      # Apache::SessionManager configuration (see 'perldoc Apache::SessionManager')
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerName MASONSESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/session_data/mason"
    

F:

   #
   # masonhandler.pl: HTML::Mason startup configuration Perl script
   # By Enrico Sorcinelli 
   package HTML::Mason;
   use HTML::Mason;
   use HTML::Mason::ApacheHandler (args_method=>'mod_perl');
   use strict;
   # List of all modules that will be used
   {
       package HTML::Mason::Commands;
       use DBI;
       use LWP;
       use Apache::SessionManager;
       ...
   }

   # Create Mason object
   my $ah = new HTML::Mason::ApacheHandler (
           comp_root => '/usr/local/apache/htdocs/mason',
           data_dir  => '/usr/local/apache/htdocs/mason/data',
           allow_globals => [ '$session' ]
                                           );
   sub handler {
       my ($r) = @_;
       return $ah->handle_request($r);
   }

   1;  

In the case you don't have access to F, you can put similar
directive directly into an F<.htaccess> file:

   PerlRequire /usr/local/apache/conf/masonhandler.pl
   
      SetHandler perl-script
      PerlHandler HTML::Mason

      PerlHeaderParserHandler Apache::SessionManager
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerName MASONSESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/session_data/mason"
      PerlSetVar SessionManagerDebug 5
   

The only difference is that you cannot use C directive (I used
C) and you must install
L in C
 phase of
Apache request instead of C phase.

Moreover, using F<.htaccess> is less flexible and efficient because
C starts F at run-time on each request.

=head3 CONFIGURATION VIA F

This is the easiest of the previous configuration. You must add a few
C directives into Apache's configuration files. 

This method is very easy to use and is appropriate for most uses of
L . 

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager

   Alias /mason "/usr/local/apache/htdocs/mason"
   
      SetHandler perl-script
      PerlHandler HTML::Mason::ApacheHandler
      PerlSetVar MasonCompRoot /usr/local/apache/htdocs/mason
      PerlSetVar MasonDataDir /usr/local/apache/htdocs/mason/data
      PerlSetVar MasonAllowGlobals $session

      PerlHeaderParserHandler Apache::SessionManager
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerName MASONSESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/session_data/mason"
      PerlSetVar SessionManagerDebug 5
    

In the case you don't have access to F, you can put similar
directive directly into an F<.htaccess> file:

   
      SetHandler perl-script
      PerlHandler HTML::Mason::ApacheHandler
      PerlSetVar MasonCompRoot /usr/local/apache/htdocs/mason
      PerlSetVar MasonDataDir /usr/local/apache/htdocs/mason/data
      PerlSetVar MasonAllowGlobals $session

      PerlHeaderParserHandler Apache::SessionManager
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerName MASONSESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/session_data/mason"
      PerlSetVar SessionManagerDebug 5
    


=head3 NOTES ON USING F<.htaccess> INSTEAD OF F

=over 4

=item *

In both cases it is necessary to install
L in C
 phase and
not into C phase (in this phase, F<.htaccess> hasn't yet  been
processed).

=item *

Using F<.htaccess>, it is possible to use only cookies for the session
tracking.

=back

=head2 THE AUTOHANDLER

This is the autohandler F:

   <%init>
   local $session = Apache::SessionManager::get_session($r);
   
   <% $m->call_next %>

=head2 TESTING Apache::SessionManager

Now, you you can use C<$session> (hash reference) in all pages managed by 
L. For example this is
F: 

   <%perl>
      my $foo = 'bla bla';

      $$session{'foo'} = $foo;
      # same as 
      $session->{'foo'} = $foo;

      print $$session{'bar'};
   

=head2 SEE ALSO

L, L,
L,
L,
L, L,
L, perl(1)

=head1 Apache::SessionManager WITH PLP

=head2 INTRODUCTION

This section describes use of L
with L. L (L) is yet another Perl
embedder, primarily for HTML documents. 

Unlike with other Perl embedders, there is no need to learn a meta-syntax or
object model: one can just use the normal Perl constructs. PLP runs under
mod_perl for speeds comparable to those of PHP, but can also be run as a CGI
script. Note that the session management it is possible only under mod_perl
environment.

=head2 CONFIGURATION

The idea is to use a global variable C<$session> in order to store session
object, and to initialize it into C sub of PLP processor.

To do it, you must patch I with following lines (you can find the patch
also in I shipped with
L distribution):

   --- PLP.pm	Fri Oct 18 21:47:07 2002
   +++ PLP.pm-patched	Fri May 30 11:38:37 2003
   @@ -317,6 +317,13 @@
        {
    	package PLP::Script;
    	use vars qw(%headers %header %cookies %cookie %get %post %fields);
   +
   +	use vars qw($session);
   +	eval { require Apache::SessionManager };
   +	unless ( $@ ) {
   +		$session = Apache::SessionManager::get_session(Apache->request);
   +	}
   +
    	*headers = \%header;
    	*cookies = \%cookie;
    	PLP::Functions->import();

To apply the patch do (before installing PLP):

   #> cd /path/to/src/PLP-3.18
   #> patch -p0 < /path/to/PLP-3.18.patch

then you can continue installing PLP normally.

However you could use session management even without patching I at
the cost of a bit of extra code in your CGI scripts (see C section).

=head3 CONFIGURATION VIA F

In F (or any files included by the C directive):

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager

   Alias /plp "/usr/local/apache/htdocs/plp"
   
      SetHandler perl-script
      PerlHandler PLP
      PerlSendHeader On
      PerlSetVar PLPcache On

      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 90
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerName PLPSESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data/plp"
      PerlSetVar SessionManagerDebug 5
    

=head3 CONFIGURATION VIA F<.htaccess>

In the case you don't have access to F, you can put similar
directive directly into an F<.htaccess> file:

   
      SetHandler perl-script
      PerlHandler PLP
      PerlSendHeader On
      PerlSetVar PLPcache On

      PerlHeaderParserHandler Apache::SessionManager
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerName PLPSESSIONID
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data/plp"
      PerlSetVar SessionManagerDebug 5
   

The only difference is that you cannot use C directive (I used
C) and you must install
L in C
 phase of
Apache request instead of C phase.

=head3 NOTES ON USING F<.htaccess> INSTEAD OF F

=over 4

=item *

In this cases it is necessary to install
L in C
 phase and
not into C phase (in this phase, F<.htaccess> hasn't yet  been
processed).

=item *

Using F<.htaccess>, it is possible to use only cookies for the session
tracking.

=back

=head2 TESTING Apache::SessionManager

Now you you can use C<$session> (hash reference) in all pages managed by PLP.
For example this is F:

   <: 
      my $title = 'Session management with PLP'; 
   :>
   
   
   <: print $title :>
   
   <:
      use Data::Dumper;
      print "
$title
";
   :>
   Session dump
   <:
      print Dumper($session);
      $session->{$$ . '-' . rand()} = rand;
   :>
   

   
    

The previous example assumes that you've patched F. Without the patch
you must add the following line before using C<$session> hash reference:

   <:
      my $session = Apache::SessionManager::get_session(Apache->request);
   :>

=head2 SEE ALSO

L, L,
L,
L,
L, L,
L, perl(1)

=head1 Apache::SessionManager WITH THE TEMPLATE TOOLKIT

=head2 INTRODUCTION

This section describes how to use
L with Template Toolkit
(L). The idea is to use the
L
plugin (available on CPAN), the TT2 wrapper around
L.

The Template Toolkit is a set of Perl modules which collectively implement a
template processing system. In this context, a template is a text document
containing special markup tags called 'directives'.

TT2 runs under mod_perl for speeds, but can also be run as a CGI script. Note
that this session management is possible only under mod_perl environment.

=head2 USING Apache::Template

This section illustrates how to use session manager TT2 plugin for use within
L mod_perl extension.

The L module provides a simple interface to
the Template Toolkit allowing Apache to serve directly TT2 files.

=head3 CONFIGURATION VIA F

In F (or any files included by the C directive):

   
      PerlModule Apache::Template

      TT2Trim             On
      TT2PostChomp        On
      TT2EvalPerl         On
      TT2Params           uri env params
      TT2IncludePath      /usr/local/apache/htdocs/tt2/includes
      TT2PreProcess       config header
      TT2PostProcess      footer

      PerlModule Apache::SessionManager
      PerlTransHandler Apache::SessionManager

      

         SetHandler perl-script
         PerlHandler Apache::Template

         PerlSetVar SessionManagerTracking On
         PerlSetVar SessionManagerExpire 600
         PerlSetVar SessionManagerInactivity 60
         PerlSetVar SessionManagerName TT2SESSIONID
         PerlSetVar SessionManagerDebug 5
         PerlSetVar SessionManagerStore File
         PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data"

      
      

=head3 CONFIGURATION VIA F<.htaccess>

In the case you don't have access to F, you can put similar
directives  directly into an F<.htaccess> file:

   
      PerlModule Apache::Template
      

         SetHandler perl-script
         PerlHandler Apache::Template

         PerlHeaderParserHandler Apache::SessionManager
         PerlSetVar SessionManagerTracking On
         PerlSetVar SessionManagerExpire 600
         PerlSetVar SessionManagerInactivity 60
         PerlSetVar SessionManagerName TT2SESSIONID
         PerlSetVar SessionManagerDebug 5
         PerlSetVar SessionManagerStore File
         PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data"

      
      

The only difference is that you cannot use C directive (I used
C) and you must install
L in C
 phase of
Apache request instead of C phase.

Now you can use C plugin by 'USE' it
in tt2 template file. This is a F TT2 template: 

   [% USE my_sess = Apache.SessionManager %]
   
   
   Session management with Apache::Template
   

   The Session Dump
   [% USE dumper %]
   
   [% dumper.dump(my_sess.session) %]
   


   
Getting session values

   Sigle session value

   ID is [% my_sess.get('_session_id') %]


   Multiple session values

   [% FOREACH s = my_sess.get('_session_id','_session_timestamp') %]
   * [% s %]

   [% END %]


   Multiple values by array ref

   [% keys = [ '_session_id', '_session_start' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]

   [% END %]

   All session values

   [% FOREACH s = my_sess.get %]
   * [% s %]

   [% END %]

   
Setting session values:

   ID: [% my_sess.set('foo' => 10, 'bar' => 20, '_session_test' => 'test') %]


   
      

Save it under the root web directory and launch it with
http://localhost/session.tt2

This is an example of deleting session keys and destroying session itself:

   [% USE my_sess = Apache.SessionManager %]
   
   
   Session management with Apache::Template
   
   
   [% USE dumper %]
   [% dumper.dump(my_sess.session) %]
   


   
Delete session values:

   [% my_sess.delete('foo','bar','_session_id') %]


   Delete session values by array ref:
   [% keys = ['foo','bar','_session_id'];
      my_sess.delete(keys) %]


   
Destroy session

   [% my_sess.destroy %]


   
      

=head3 NOTES ON USING F<.htaccess> INSTEAD OF F

=over 4

=item *

In this cases it is necessary to install
L in C
  phase
and not into C phase (in this phase, F<.htaccess> hasn't yet 
been processed).

=item *

Using F<.htaccess>, it is possible to use only cookies for the session
tracking.

=back

=head2 USING CGI scripts 

This section illustrates how to use session manager TT2 plugin for use in CGI
scripts under L or
L environment. 

=head3 CONFIGURATION VIA F

This example assumes that you can access to F. If not, you must see
the C on previous section about
configuring it via F<.htaccess>.

   
      Alias /perl/ /usr/local/apache/perl-scripts/ 
      PerlModule Apache::SessionManager
      PerlTransHandler Apache::SessionManager
       
         SetHandler perl-script
         PerlHandler Apache::Registry
         PerlSendHeader On
         PerlSetupEnv   On
         Options ExecCGI 

         PerlSetVar SessionManagerTracking On
         PerlSetVar SessionManagerExpire 600
         PerlSetVar SessionManagerInactivity 60
         PerlSetVar SessionManagerName TT2SESSIONID
         PerlSetVar SessionManagerDebug 5
         PerlSetVar SessionManagerStore File
         PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_session_data"
      
      

This is the simple CGI script I:

   #!/usr/bin/perl

   use strict;
   use Template;

   my $file = 'session.tt2';
   my $vars = {
      title  => "Session management in a CGI Apache::Registry environment\n"
   };

   my $template = Template->new();
   $template->process($file, $vars)
      || die "Template process failed: ", $template->error(), "\n";

and this is a F TT2 template (it's the same than the
L version!)

   [% USE my_sess = Apache.SessionManager %]
   
   
   [% title %]
   

   The session dump
   [% USE dumper %]
   
   [% dumper.dump(my_sess.session) %]
   


   
Getting session values

   Sigle session value

   ID is [% my_sess.get('_session_id') %]


   Multiple session values

   [% FOREACH s = my_sess.get('_session_id','_session_timestamp') %]
   * [% s %]

   [% END %]


   Multiple values by array ref

   [% keys = [ '_session_id', '_session_start' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]

   [% END %]

   All session values

   [% FOREACH s = my_sess.get %]
   * [% s %]

   [% END %]

   
Setting session values:

   ID: [% my_sess.set('foo' => 10, 'bar' => 20, '_session_test' => 'test') %]


   
     

Save both into the F directory and launch
http://localhost/perl/session.cgi

=head2 SEE ALSO

L, L