Apache-SessionManager

 view release on metacpan or  search on metacpan

SessionManager/cookpod.pod  view on Meta::CPAN

         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
      </FilesMatch>
   </IfModule>   

The only difference is that you cannot use C<Location> directive (I used
C<FilesMatch>) and you must install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase of
Apache request instead of C<URI translation> phase.

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

=over 4

=item *

In this cases it is necessary to install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase and
not into C<URI translation> 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<CGI::Application|CGI::Application> in order to supply the
C<cgiapp_init> 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</usr/local/apache/cgi-application/CGI/Application/SessionManager.pm>.

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<CGI::Application|CGI::Application>.

Then we write F<WebApp.pm> 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 = '<PRE>' . Dumper($self->{'session'}) . '<PRE>';
        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</usr/local/apache/cgi-application/WebApp.pm>.

=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<run()>. Following is the entirety
of F</usr/local/apache/cgi-application/webapp.cgi>:

   #!/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<Apache::SessionManager|Apache::SessionManager>,
L<CGI::Application|CGI::Application>, L<Apache|Apache>, perl

=head1 Apache::SessionManager WITH CGI::Builder

=head2 INTRODUCTION

This section describes how to use
L<Apache::SessionManager|Apache::SessionManager> with
L<CGI::Builder|CGI::Builder> toolkit.

L<CGI::Builder|CGI::Builder> 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.

SessionManager/cookpod.pod  view on Meta::CPAN

      PerlSetVar SessionManagerDebug 5
   </Location> 

=head3 CONFIGURATION VIA F<.htaccess>

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

   <FilesMatch "\.plp$">
      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
   </FilesMatch>

The only difference is that you cannot use C<Location> directive (I used
C<FilesMatch>) and you must install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase of
Apache request instead of C<URI translation> phase.

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

=over 4

=item *

In this cases it is necessary to install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase and
not into C<URI translation> 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</usr/local/apache/htdocs/plp/session.plp>:

   <: 
      my $title = 'Session management with PLP'; 
   :>
   <HTML>
   <HEAD>
   <TITLE><: print $title :></TITLE>
   <BODY>
   <:
      use Data::Dumper;
      print "<H1>$title</H1>";
   :>
   <B>Session dump</B><PRE>
   <:
      print Dumper($session);
      $session->{$$ . '-' . rand()} = rand;
   :>
   </PRE>
   </BODY>
   </HTML> 

The previous example assumes that you've patched F<PLP.pm>. 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<PLP|PLP>, L<Apache::Session|Apache::Session>,
L<Apache::Session::Flex|Apache::Session::Flex>,
L<Apache::SessionManager|Apache::SessionManager>,
L<Apache::Request|Apache::Request>, L<Apache::Cookie|Apache::Cookie>,
L<Apache|Apache>, perl(1)

=head1 Apache::SessionManager WITH THE TEMPLATE TOOLKIT

=head2 INTRODUCTION

This section describes how to use
L<Apache::SessionManager|Apache::SessionManager> with Template Toolkit
(L<http://www.tt2.org>). The idea is to use the
L<Template::Plugin::Apache::SessionManager|Template::Plugin::Apache::SessionManager>
plugin (available on CPAN), the TT2 wrapper around
L<Apache::SessionManager|Apache::SessionManager>.

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<Apache::Template|Apache::Template> mod_perl extension.

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

=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::Template

      TT2Trim             On

SessionManager/cookpod.pod  view on Meta::CPAN

   %> lwp-download http://search.cpan.org/CPAN/authors/id/E/EN/ENRYS/Apache-SessionManager-0.06.tar.gz
   %> tar -xzvf Apache-SessionManager-0.06.tar.gz
   %> cd Apache-SessionManager-0.06
   %> PERL5LIB=/path/to/your/perl-lib/lib/site_perl:/path/to/your/perl-lib/lib \
      perl Makefile.PL PREFIX=/path/to/your/perl-lib
   %> make
   %> PERL5LIB=/path/to/your/perl-lib/lib/site_perl:/path/to/your/perl-lib/lib \
      make test
   %> make install

To test the installation:

   %> PERL5LIB=/path/to/your/perl-lib/lib/site_perl perldoc Apache::SessionManager 

=head2 TESTING Apache::SessionManager

Tipically, without system administration account you cannot manage Apache
F<httpd.conf>.

Also if you cannot install (or run) another C<httpd> instance even at high
ports (for example > 1024) the only possibilty to use session manager is to
configure F<.htaccess> file appropriately.

Using F<.htaccess>, you must install
L<Apache::SessionManager|Apache::SessionManager> in C<Header parsing> phase of
Apache request instead of C<URI translation> phase. Moreover, it is possible to
use only cookies for the session tracking.

This is an example of how configure F<.htaccess> file for use session (using
file system as backend datastore) with CGI scripts under 
L<Apache::Registry|Apache::Registry>:

   <IfModule mod_perl.c>
      <Perl>
         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