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>
SessionManager/cookpod.pod view on Meta::CPAN
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
</FilesMatch>
=head3 NOTES ON USING F<.htaccess> INSTEAD OF F<httpd.conf>
=over 4
=item *
In both 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 THE AUTOHANDLER
This is the autohandler F</usr/local/apache/htdocs/mason/autohandler>:
<%init>
local $session = Apache::SessionManager::get_session($r);
</%init>
<% $m->call_next %>
=head2 TESTING Apache::SessionManager
Now, you you can use C<$session> (hash reference) in all pages managed by
L<HTML::Mason|HTML::Mason>. For example this is
F</usr/local/apache/htdocs/mason/session.html>:
<%perl>
my $foo = 'bla bla';
$$session{'foo'} = $foo;
# same as
$session->{'foo'} = $foo;
print $$session{'bar'};
</%perl>
=head2 SEE ALSO
L<HTML::Mason|HTML::Mason>, 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 PLP
=head2 INTRODUCTION
This section describes use of L<Apache::SessionManager|Apache::SessionManager>
with L<PLP|PLP>. L<PLP|PLP> (L<http://plp.juerd.nl/>) 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<start> sub of PLP processor.
To do it, you must patch I<PLP.pm> with following lines (you can find the patch
also in I<patches/PLP-3.18.patch> shipped with
L<Apache::SessionManager|Apache::SessionManager> 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<PLP.pm> at
the cost of a bit of extra code in your CGI scripts (see C<Testing
Apache::SessionManager> section).
=head3 CONFIGURATION VIA F<httpd.conf>
In F<httpd.conf> (or any files included by the C<Include> directive):
PerlModule Apache::SessionManager
PerlTransHandler Apache::SessionManager
SessionManager/cookpod.pod view on Meta::CPAN
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
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>
SessionManager/cookpod.pod view on Meta::CPAN
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
The installation procedure for L<Digest::MD5|Digest::MD5> or
L<Apache::Cookie|Apache::Cookie> (libapreq) is almost the same.
=head2 INSTALLING Apache::Session
%> lwp-download http://search.cpan.org/CPAN/authors/id/J/JB/JBAKER/Apache-Session-1.54.tar.gz
%> tar -xzvf Apache-Session-1.54.tar.gz
%> cd Apache-Session-1.54
%> perl Makefile.PL PREFIX=/path/to/your/perl-lib
%> PERL5LIB=/path/to/your/perl-lib/lib make test
%> make install
Plese note that the environment variable C<PERL5LIB> setting is necessary
before run tests in order to append F</path/to/your/perl-lib/lib> to C<@INC>.
=head2 INSTALLING Apache::SessionManager
%> 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
SessionManager/cookpod.pod view on Meta::CPAN
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>
Optionally, you can set C<SessionManagerExpire> with value C<none>(or C<no> or
C<disable>) in order to disable expiration session control at server side.
However, it is not completely safe to left session expiration policies only on
the client side. A C<SessionManagerExpire> value should be always defined.
=head1 SEE ALSO
L<Apache::SessionManager|Apache::SessionManager>,L<Apache::Request|Apache::Request>,
L<Apache::Cookie|Apache::Cookie>, L<Apache|Apache>, perl(1)
=head1 AUTHORS
Enrico Sorcinelli <enrico@sorcinelli.it>
=head1 VERSION
0.06
=head1 BUGS
Send bug reports and comments to: enrico@sorcinelli.it In each report please
include the module version, the Perl version, the Apache, the mod_perl version
and your OS. If the problem is browser dependent please include also browser
name and version.
Patches are welcome and I'll update the document if any problems or errors
will be found.
=head1 COPYRIGHT AND LICENSE
Copyright (C) 2001-2003 Enrico Sorcinelli. All rights reserved.
This program is free software; you can redistribute it
and/or modify it under the same terms as Perl itself.
=cut
( run in 0.468 second using v1.01-cache-2.11-cpan-39bf76dae61 )