NAME

Template::Plugin::Apache::SessionManager - Session manager Template Toolkit plugin

SYNOPSIS

   [% USE my_sess = Apache.SessionManager %]

   # Getting single session value
   SID = [% my_sess.get('_session_id') %]

   # Getting multiple session values
   [% FOREACH s = my_sess.get('_session_id','_session_timestamp') %]
   * [% s %]
   [% END %]
   # same as
   [% keys = ['_session_id','_session_timestamp'];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]
   [% END %]

   # Getting all session values
   [% FOREACH s = my_sess.get %]
   * [% s %]
   [% END %]

   # Setting session values:
   [% my_sess.set('foo' => 10, 'bar' => 20, ...) %]

   # Deleting session value(s)
   [% my_sess.delete('foo', 'bar') %]
   # same as
   [% keys = ['foo', 'bar'];
      my_sess.delete(keys) %]

   # Destroying session
   [% my_sess.destroy %]

DESCRIPTION

This Template Toolkit plugin provides an interface to Apache::SessionManager module wich provides a session manager for a web application. This modules allows you to integrate a transparent session management into your template documents (it handles for you the cookie/URI session tracking management of a web application)

An Apache.SessionManager plugin object can be created as follows:

   [% USE my_sess = Apache.SessionManager %]

or directly:

   [% USE Apache.SessionManager %]

This restore a pre-existent session (or create new if this fails). You can then use the plugin methods.

METHODS

get([array])

Reads a session value(s) and returns an array containing the keys values:

   Session id is [% my_sess.get('_session_id') %]

   [% FOREACH s = my_sess.get('foo', 'bar') %]
   * [% s %]
   [% END %]

Also it is possible to call get method:

   [% keys = [ 'foo', 'bar' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]
   [% END %]

Called with no args, returns all keys values.

set(hash)

Set session values

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

Called with no args, has no effects.

delete(array)

Delete session values

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

Also it is possible to call delete method:

   [% keys = [ 'foo', 'bar' ];
      my_sess.delete(keys) %]

Called with no args, has no effects.

destroy

Destroy current session

   [% my_sess.destroy %]

WHAT DOES Apache::SessionManager DO

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

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.

USING Apache::Template

This section illustrates how to use session manager TT2 plugin for use within Apache::Template mod_perl extension.

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

CONFIGURATION VIA httpd.conf

In httpd.conf (or any files included by the Include directive):

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

      <LocationMatch "\.tt2$">

         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"

      </LocationMatch>
   </IfModule>

CONFIGURATION VIA .htaccess

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

   <IfModule mod_perl.c>
      PerlModule Apache::Template
      <FilesMatch "\.tt2$">

         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"

      </FilesMatch>
   </IfModule>

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

Now you can use Template:Plugin::Apache::SessionManager plugin by 'USE' it in TT2 template file. This is a session.tt2 TT2 template:

   [% USE my_sess = Apache.SessionManager %]
   <HTML>
   <HEAD>
   <TITLE>Session management with Apache::Template</TITLE>
   <BODY>

   The Session Dump
   [% USE dumper %]
   <PRE>
   [% dumper.dump(my_sess.session) %]
   </PRE>

   <H3>Getting session values</H3>
   Sigle session value<BR>
   ID is [% my_sess.get('_session_id') %]<P>

   Multiple session values<BR>
   [% FOREACH s = my_sess.get('_session_id','_session_timestamp') %]
   * [% s %]<BR>
   [% END %]<P>

   Multiple values by array ref<BR>
   [% keys = [ '_session_id', '_session_start' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]<BR>
   [% END %]

   All session values<BR>
   [% FOREACH s = my_sess.get %]
   * [% s %]<BR>
   [% END %]

   <H3>Setting session values:</H3>
   ID: [% my_sess.set('foo' => 10, 'bar' => 20, '_session_test' => 'test') %]<BR>

   </BODY>
   </HTML>

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 %]
   <HTML>
   <HEAD>
   <TITLE>Session management with Apache::Template</TITLE>
   <BODY>
   <PRE>
   [% USE dumper %]
   [% dumper.dump(my_sess.session) %]
   </PRE>

   <H3>Delete session values:</H3>
   [% my_sess.delete('foo','bar','_session_id') %]<BR>

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

   <H3>Destroy session</H3>
   [% my_sess.destroy %]<BR>

   </BODY>
   </HTML>

NOTES ON USING .htaccess INSTEAD OF httpd.conf

In this cases it is necessary to install Apache::SessionManager in Header parsing phase and not into URI translation phase (in this phase, .htaccess hasn't yet been processed).
Using .htaccess, it is possible to use only cookies for the session tracking.

USING CGI scripts

This section illustrates how to use session manager TT2 plugin for use in CGI scripts under Apache::Registry or Apache::PerlRun environment.

CONFIGURATION VIA httpd.conf

This example assumes that you can access to httpd.conf. If not, you must see the NOTES ON USING .htaccess INSTEAD OF httpd.conf on previous section about configuring it via .htaccess.

   <IfModule mod_perl.c>
      Alias /perl/ /usr/local/apache/perl-scripts/ 
      PerlModule Apache::SessionManager
      PerlTransHandler Apache::SessionManager
      <Location /perl> 
         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"
      </Location>
   </IfModule>

This is the simple CGI script session.cgi:

   #!/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 session.tt2 TT2 template (it's the same than the Apache::Template version!)

   [% USE my_sess = Apache.SessionManager %]
   <HTML>
   <HEAD>
   <TITLE>[% title %]</TITLE>
   <BODY>

   The session dump
   [% USE dumper %]
   <PRE>
   [% dumper.dump(my_sess.session) %]
   </PRE>

   <H3>Getting session values</H3>
   Sigle session value<BR>
   ID is [% my_sess.get('_session_id') %]<P>

   Multiple session values<BR>
   [% FOREACH s = my_sess.get('_session_id','_session_timestamp') %]
   * [% s %]<BR>
   [% END %]<P>

   Multiple values by array ref<BR>
   [% keys = [ '_session_id', '_session_start' ];
      FOREACH s = my_sess.get(keys) %]
   * [% s %]<BR>
   [% END %]

   All session values<BR>
   [% FOREACH s = my_sess.get %]
   * [% s %]<BR>
   [% END %]

   <H3>Setting session values:</H3>
   ID: [% my_sess.set('foo' => 10, 'bar' => 20, '_session_test' => 'test') %]<BR>

   </BODY>
   </HTML>

Save both into the /usr/local/apache/perl-scripts directory and launch http://localhost/perl/session.cgi

AUTHORS

Enrico Sorcinelli <enrico@sorcinelli.it>

BUGS

This library has been tested by the author with Perl versions 5.005, 5.6.0 and 5.6.1 on different platforms: Linux 2.2 and 2.4, Solaris 2.6 and 2.7.

Send bug reports and comments to: enrico@sorcinelli.it. In each report please include the version module, the Perl version, the Apache, the mod_perl version and your SO. If the problem is browser dependent please include also browser name and version. Patches are welcome and I'll update the module if any problems will be found.

VERSION

Version 0.02

COPYRIGHT AND LICENSE

To install Template::Plugin::Apache::SessionManager, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Template::Plugin::Apache::SessionManager

CPAN shell

perl -MCPAN -e shell
install Template::Plugin::Apache::SessionManager

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

get([array])

set(hash)

delete(array)

destroy

WHAT DOES Apache::SessionManager DO

USING Apache::Template

CONFIGURATION VIA httpd.conf

CONFIGURATION VIA .htaccess

NOTES ON USING .htaccess INSTEAD OF httpd.conf

USING CGI scripts

CONFIGURATION VIA httpd.conf

AUTHORS

BUGS

VERSION

SEE ALSO

COPYRIGHT AND LICENSE

Module Install Instructions