--- name: "Apache::Session::Wrapper" section: "3pm" platform: "linux" package: "libapache-session-wrapper-perl" version: "0.34-4" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Apache::Session::Wrapper" --- # Apache::Session::Wrapper(3pm) A simple wrapper around Apache::Session ## 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, \ ## 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.