Provided by: libapache-session-wrapper-perl_0.34-3_all bug

NAME

       Apache::Session::Wrapper - A simple wrapper around Apache::Session

SYNOPSIS

        my $wrapper =
            Apache::Session::Wrapper->new( class  => 'MySQL',
                                           handle => $dbh,
                                           cookie_name => 'example-dot-com-cookie',
                                         );

        # will get an existing session from a cookie, or create a new session
        # and cookie if needed
        $wrapper->session->{foo} = 1;

DESCRIPTION

       This module is a simple wrapper around Apache::Session which provides some methods to
       simplify getting and setting the session id.

       It can uses cookies to store the session id, or it can look in a provided object for a
       specific parameter.  Alternately, you can simply provide the session id yourself in the
       call to the "session()" method.

       If you're using Mason, you should probably take a look at
       "MasonX::Request::WithApacheSession" first, which integrates this module directly into
       Mason.

METHODS

       This class provides the following public methods:

       •   new

           This method creates a new "Apache::Session::Wrapper" object.

           If the parameters you provide are not correct (wrong type, missing parameters, etc.),
           this method throws an "Apache::Session::Wrapper::Exception::Params" exception.  You
           can treat this exception as a string if you want.

       •   session

           This method returns a hash tied to the "Apache::Session" class.

           This method accepts an optional "session_id" parameter.

       •   delete_session

           This method deletes the existing session from persistent storage.  If you are using
           the built-in cookie handling, it also deletes the cookie in the browser.

CONFIGURATION

       This module accepts quite a number of parameters, most of which are simply passed through
       to "Apache::Session".  For this reason, you are advised to familiarize yourself with the
       "Apache::Session" documentation before attempting to configure this module.

       You can also register "Apache::Session" classes, or the classes used for doing the work in
       "Apache::Session::Flex". See REGISTERING CLASSES for details.

   Supported Classes
       The following classes are already supported and do not require registration:

       •   Apache::Session::MySQL

       •   Apache::Session::Postgres

       •   Apache::Session::Oracle

       •   Apache::Session::Informix

       •   Apache::Session::Sybase

       •   Apache::Session::File

       •   Apache::Session::DB_File

       •   Apache::Session::PHP

       •   Apache::Session::Flex

       The following classes can be used with "Apache::Session::Flex":

       •   Apache::Session::Store::MySQL

       •   Apache::Session::Store::Postgres

       •   Apache::Session::Store::Informix

       •   Apache::Session::Store::Oracle

       •   Apache::Session::Store::Sybase

       •   Apache::Session::Store::File

       •   Apache::Session::Store::DB_File

       •   Apache::Session::Store::PHP

       •   Apache::Session::Lock::MySQL

       •   Apache::Session::Lock::File

       •   Apache::Session::Lock::Null

       •   Apache::Session::Lock::Semaphore

       •   Apache::Session::Generate::MD5

       •   Apache::Session::Generate::ModUsertrack

       •   Apache::Session::Serialize::Storable

       •   Apache::Session::Serialize::Base64

       •   Apache::Session::Serialize::Sybase

       •   Apache::Session::Serialize::UUEncode

       •   Apache::Session::Serialize::PHP

   Generic Parameters
       •   class  =>  class name

           The name of the "Apache::Session" subclass you would like to use.

           This module will load this class for you if necessary.

           This parameter is required.

       •   always_write  =>  boolean

           If this is true, then this module will ensure that "Apache::Session" writes the
           session.  If it is false, the default "Apache::Session" behavior is used instead.

           This defaults to true.

       •   allow_invalid_id  =>  boolean

           If this is true, an attempt to create a session with a session id that does not exist
           in the session storage will be ignored, and a new session will be created instead.  If
           it is false, a "Apache::Session::Wrapper::Exception::NonExistentSessionID" exception
           will be thrown instead.

           This defaults to true.

       •   session_id  =>  string

           Try this session id first and use it if it exist. If the session does not exist, it
           will ignore this parameter and make a new session.

   Cookie-Related Parameters
       •   use_cookie  =>  boolean

           If true, then this module will use one of "Apache::Cookie", "Apache2::Cookie" or
           "CGI::Cookie" (as appropriate) to set and read cookies that contain the session id.

       •   cookie_name  =>  name

           This is the name of the cookie that this module will set.  This defaults to "Apache-
           Session-Wrapper-cookie".  Corresponds to the "Apache::Cookie" "-name" constructor
           parameter.

       •   cookie_expires  =>  expiration

           How long before the cookie expires.  This defaults to 1 day, "+1d".  Corresponds to
           the "-expires" parameter.

           As a special case, you can set this value to "session" to have the "-expires"
           parameter set to undef, which gives you a cookie that expires at the end of the
           session.

       •   cookie_domain  =>  domain

           This corresponds to the "-domain" parameter.  If not given this will not be set as
           part of the cookie.

           If it is undefined, then no "-domain" parameter will be given.

       •   cookie_path  =>  path

           Corresponds to the "-path" parameter.  It defaults to "/".

       •   cookie_secure  =>  boolean

           Corresponds to the "-secure" parameter.  It defaults to false.

       •   cookie_resend  =>  boolean

           By default, this parameter is true, and the cookie will be sent for every request.  If
           it is false, then the cookie will only be sent when the session is created.  This is
           important as resending the cookie has the effect of updating the expiration time.

       •   header_object => object

           When running outside of mod_perl, you must provide an object to which the cookie
           header can be added.  This object must provide an "err_headers_out()" or
           "headers_out()" method.

           Under mod_perl 1, this will default to the object returned by "Apache->request()".
           Under mod_perl 2 we call "Apache2::RequestUtil->request()"

   Query/POST-Related Parameters
       •   param_name  =>  name

           If set, then this module will first look for the session id in the object specified
           via "param_object".  This parameter determines the name of the parameter that is
           checked.

           If you are also using cookies, then the module checks the param object first, and then
           it checks for a cookie.

       •   param_object  =>  object

           This should be an object that provides a "param()" method.  This object will be
           checked to see if it contains the parameter named in "params_name".  This object will
           probably be a "CGI.pm" or "Apache::Request" object, but it doesn't have to be.

   Apache::Session-related Parameters
       These parameters are simply passed through to "Apache::Session".

       •   data_source  =>  DSN

           Corresponds to the "DataSource" parameter passed to the DBI-related session modules.

       •   user_name  =>  user name

           Corresponds to the "UserName" parameter passed to the DBI-related session modules.

       •   password  =>  password

           Corresponds to the "Password" parameter passed to the DBI-related session modules.
           Defaults to undef.

       •   handle =>  DBI handle

           Corresponds to the "Handle" parameter passed to the DBI-related session modules.  This
           cannot be set via the httpd.conf file, because it needs to be an actual Perl variable,
           not the name of that variable.

       •   table_name  =>  table name

           Corresponds to the "TableName" paramaeter passed to DBI-related modules.

       •   lock_data_source  =>  DSN

           Corresponds to the "LockDataSource" parameter passed to "Apache::Session::MySQL".

       •   lock_user_name  =>  user name

           Corresponds to the "LockUserName" parameter passed to "Apache::Session::MySQL".

       •   lock_password  =>  password

           Corresponds to the "LockPassword" parameter passed to "Apache::Session::MySQL".
           Defaults to undef.

       •   lock_handle  =>  DBI handle

           Corresponds to the "LockHandle" parameter passed to the DBI-related session modules.
           As with the "handle" parameter, this cannot be set via the httpd.conf file.

       •   commit =>  boolean

           Corresponds to the "Commit" parameter passed to the DBI-related session modules.

       •   transaction  =>  boolean

           Corresponds to the "Transaction" parameter.

       •   directory  =>  directory

           Corresponds to the "Directory" parameter passed to "Apache::Session::File".

       •   lock_directory  =>  directory

           Corresponds to the "LockDirectory" parameter passed to "Apache::Session::File".

       •   file_name  =>  file name

           Corresponds to the "FileName" parameter passed to "Apache::Session::DB_File".

       •   store  =>  class

           Corresponds to the "Store" parameter passed to "Apache::Session::Flex".

       •   lock  =>  class

           Corresponds to the "Lock" parameter passed to "Apache::Session::Flex".

       •   generate  =>  class

           Corresponds to the "Generate" parameter passed to "Apache::Session::Flex".

       •   serialize  =>  class

           Corresponds to the "Serialize" parameter passed to "Apache::Session::Flex".

       •   textsize  =>  size

           Corresponds to the "textsize" parameter passed to "Apache::Session::Sybase".

       •   long_read_len  =>  size

           Corresponds to the "LongReadLen" parameter passed to "Apache::Session::MySQL".

       •   n_sems  =>  number

           Corresponds to the "NSems" parameter passed to "Apache::Session::Lock::Semaphore".

       •   semaphore_key  =>  key

           Corresponds to the "SemaphoreKey" parameter passed to
           "Apache::Session::Lock::Semaphore".

       •   mod_usertrack_cookie_name  =>  name

           Corresponds to the "ModUsertrackCookieName" parameter passed to
           "Apache::Session::Generate::ModUsertrack".

       •   save_path  =>  path

           Corresponds to the "SavePath" parameter passed to "Apache::Session::PHP".

HOW COOKIES ARE HANDLED

       When run under mod_perl, this module attempts to first use "Apache::Cookie" for cookie-
       handling.  Otherwise it uses "CGI::Cookie" as a fallback.

       If it ends up using "CGI::Cookie" then you must provide a "header_object" parameter. This
       object must have an "err_headers_out()" or "headers_out()" method. It looks for these
       methods in that order. The method is expected to return an object with an API like
       "Apache::Table". It calls "add()" on the returned method to add a "Set-Cookie" header.

REGISTERING CLASSES

       In order to support any "Apache::Session" subclasses, this module provides a simple
       registration mechanism.

       You can register an "Apache::Session" subclass, or a class intended to provide a class
       that implements something required by "Apache::Session::Flex".

   Registering a Complete Subclass
       This is done by calling "Apache::Session::Wrapper->RegisterClass()":

         Apache::Session::Wrapper->RegisterClass
             ( name     => 'MyClass',
               required => [ [ qw( param1 param2 ) ],
                             [ qw( param3 param4 ) ] ],
               optional => [ 'optional_p' ],
             );

         Apache::Session::Wrapper->RegisterClass
             ( name     => 'Apache::Session::MyFile',
               required => 'File',
               optional => 'File',
             );

       The "RegisterClass()" method takes the following options:

       •   name

           This should be the name of the class you are registering. The actual class must start
           with "Apache::Session::", but this part does not need to be included when registering
           the class (it's optional).

       •   required

           These are the required parameters for this class.

           The value of this parameter can either be a string or a reference to an array of array
           references.

           If it is a string, then it identifies an existing "Apache::Session" subclass which is
           already registered or built-in, like "File" or "Postgres".

           If it an array reference, then that reference should in turn contain one or more array
           references. Each of those contained references represents one set of required
           parameters. When an "Apache::Session::Wrapper" object is constructed, only one of
           these sets must be passed in. For example:

             required => [ [ qw( p1 p2 ) ],
                           [ qw( p2 p3 p4 ) ] ]

           This says that either "p1" and "p2" must be provided, or "p2", "p3", and "p4".

           If there are no required parameters for this class, then the "required" parameter can
           be omitted.

       •   optional

           This specifies optional parameters, and should just be a simple array reference.

   Registering a Subclass for Flex
       Registering a subclass that can be used with "Apache::Session::Flex" is very similar to
       registering a complete class:

         Apache::Session::Wrapper->RegisterFlexClass
             ( name     => 'MyClass',
               type     => 'Store',
               required => [ [ qw( param1 param2 ) ],
                             [ qw( param3 param4 ) ] ],
               optional => [ 'optional_p' ],
             );

         Apache::Session::Wrapper->RegisterFlexClass
             ( name     => 'Apache::Session::Store::MyFile',
               type     => 'store',
               required => 'File',
               optional => 'File',
             );

       The "RegisterFlexClass()" method has the same parameters as "RegisterClass()", but it also
       requires a "type" parameter. This must be one of "store", "lock", "generate", or
       "serialize".

SUBCLASSING

       This class provides a simple hook for subclasses.  Before trying to get a session id from
       the URL or cookie, it calls a method named "_get_session_id()".  In this class, that
       method is a no-op, but you can override this in a subclass.

       This class is a "Class::Container" subclass, so if you accept additional constructor
       parameters, you should declare them via the "valid_params()" method.

SUPPORT

       As can be seen by the number of parameters above, "Apache::Session" has way too many
       possibilities for me to test all of them.  This means there are almost certainly bugs.

       Please submit bugs to the CPAN RT system at
       http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Apache%3A%3ASession%3A%3AWrapper or via
       email at bug-apache-session-wrapper@rt.cpan.org.

       Support questions can be sent to me at my email address, shown below.

AUTHOR

       Dave Rolsky, <autarch@urth.org>

COPYRIGHT

       Copyright (c) 2003-2006 David Rolsky.  All rights reserved.  This program is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself.

       The full text of the license can be found in the LICENSE file included with this module.