view release on metacpan or  search on metacpan

SessionManager.pm  view on Meta::CPAN

	
1;
__END__

=pod 

=head1 NAME

Apache::SessionManager - mod_perl 1.0/2.0 session manager extension to
manage sessions over HTTP requests

=head1 SYNOPSIS

In F<httpd.conf> (mod_perl 1):

   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager

   <Location /my-app-with-session>
      SetHandler perl-script
      PerlHandler Apache::MyModule
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_sessions"
   </Location>  

   <Location /my-app-without-sessions>
      PerlSetVar SessionManagerTracking Off
   </Location>

In F<httpd.conf> (mod_perl 2):

   PerlModule Apache2
   PerlModule Apache::SessionManager
   PerlTransHandler Apache::SessionManager

   <Location /my-app-with-session>
      SetHandler perl-script
      PerlResponseHandler Apache::MyModule
      PerlSetVar SessionManagerTracking On
      PerlSetVar SessionManagerExpire 3600
      PerlSetVar SessionManagerInactivity 900
      PerlSetVar SessionManagerStore File
      PerlSetVar SessionManagerStoreArgs "Directory => /tmp/apache_sessions"
   </Location>  

In a mod_perl module handler:

   sub handler {
      my $r = shift;
      my $session = Apache::SessionManager::get_session($r);
      ...
   }

=head1 DESCRIPTION

Apache::SessionManager is a mod_perl (1.0 and 2.0) module that helps session
management of a web application. This module is a wrapper around
L<Apache::Session|Apache::Session> persistence framework for session data. It
creates a session object and makes it available to all other handlers 
transparenlty by putting it in pnotes. In a mod_perl handlers you can retrieve 
the session object directly from pnotes with predefined key 
C<SESSION_MANAGER_HANDLE>:

   my $session = $r->pnotes('SESSION_MANAGER_HANDLE') ? $r->pnotes('SESSION_MANAGER_HANDLE') : ();

then it is possible to set a value in current session with:

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

or it is possible to read value session with:

   print "$$session{'key'}";
   # same as
   print $session->{'key'};	

Apache::SessionManager is intended also to use within thirdy part packages.
See L<Apache::SessionManager::cookpod|Apache::SessionManager::cookpod> for more
info.

=head1 MOD_PERL 2 COMPATIBILITY

Since version 1, Apache::SessionManager is fully compatible with both mod_perl
generations 1.0 and 2.0.

If you have mod_perl 1.0 and 2.0 installed on the same system and the two uses
the same per libraries directory, to use mod_perl 2.0 version make sure to load
first C<Apache2> module which will perform the necessary adjustements to
C<@INC>:

   PerlModule Apache2
   PerlModule Apache::SessionManager

Of course, notice that if you use mod_perl 2.0, there is no need to pre-load
the L<Apache::compat|Apache::compat> compatibility layer.

Versions of Apache::SessionManager less than 1.00 are mod_perl 1.0 only, so its 
works fine with mod_perl 2.0 only under L<Apache::compat|Apache::compat>.

=head1 API OVERVIEW

Apache::SessionManager offers two kinds of interfaces: functional and object
oriented. For a detailed description for the last one, see L</METHODS> section.

The following functions are provided (but not exported) by this module:

=over 4

=item C<Apache::SessionManager::get_session(Apache-E<gt>request)>

Return an hash reference to current session object. 

In a mod_perl module handler:

   sub handler {
      my $r = shift;
      my $session = Apache::SessionManager::get_session($r);

SessionManager.pm  view on Meta::CPAN

The module put the user start session time in a special session key 
C<_session_start>.

=item C<SessionManagerInactivity> number

This single directive defines user inactivity sessions expiration time (in
seconds).

   PerlSetVar SessionManagerInactivity 900

If not specified no user inactivity expiration policies are applied. The module
put the user timestamp in a special session key  C<_session_timestamp>.

=item C<SessionManagerName> string

This single directive defines session cookie name

   PerlSetVar SessionManagerName PSESSID

The default value is C<PERLSESSIONID>

=item C<SessionManagerCookieArgs>

With this directive you can provide optional arguments  for cookie attributes
setting. The arguments are passed as comma-separated list of name/value pairs.
The only attributes accepted are:

=over 4

=item * Domain

Set the domain for the cookie.

=item * Path

Set the path for the cookie.

=item * Secure

Set the secure flag for the cookie. 

=item * Expires

Set expire time for the cookie.

=back

For instance:

   PerlSetVar SessionManagerCookieArgs "Path   => /some-path, \
                                        Domain => .yourdomain.com, \
                                        Secure => 1"

Please see the documentation for L<Apache::Cookie|Apache::Cookie> or
L<CGI::Cookie|CGI::Cookie> in order to see more cookie arguments details.

=item C<SessionManagerStore> datastore

This single directive sets the session datastore used by
L<Apache::Session|Apache::Session> framework

   PerlSetVar SessionManagerStore File

The following datastore plugins are available with 
L<Apache::Session|Apache::Session> distribution:

=over 4

=item * File

Sessions are stored in file system

=item * MySQL

Sessions are stored in MySQL database

=item * Postgres

Sessions are stored in Postgres database

=item * Sybase

Sessions are stored in Sybase database

=item * Oracle

Sessions are stored in Oracle database

=item * DB_File

Sessions are stored in DB files

=back

In addition to datastore plugins shipped with
L<Apache::Session|Apache::Session>, you can pass the modules you want to use as
arguments to the store constructor. The Apache::Session::Whatever part is
appended for you: you should not supply it.

If you wish to use a module of your own making, you should  make sure that it
is available under the L<Apache::Session|Apache::Session> package namespace.
For example:

   PerlSetVar SessionManagerStore SharedMem

in order to use L<Apache::Session::SharedMem|Apache::Session::SharedMem> to
store sessions in RAM (but you must install
L<Apache::Session::SharedMem|Apache::Session::SharedMem>  before!)

The default value is C<File>.

=item C<SessionManagerLock> Null|MySQL|Semaphore|File

This single directive set lock manager for
L<Apache::Session::Flex|Apache::Session::Flex>. The default value is C<Null>.

=item C<SessionManagerGenerate> MD5|ModUniqueId|ModUsertrack

This single directive set session ID generator for
L<Apache::Session::Flex|Apache::Session::Flex>. The default value is C<MD5>.