Apache...rapper(3pm)

📦
version 0.34 · 4 versions
, in debian bookworm, debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

NAME 💖

Apache::Session::Wrapper — a simple wrapper around Apache::Session.

Also: this is the Apache...rapper(3pm) page from User Contributed Perl Documentation, bestie. Part 1 of 2, so buckle up. 🫶

✨ 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 use 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. iykyk

🌸 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. bye bestie 👋

👑 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 exists. If the session does not exist, it will ignore this parameter and make a new session.
  • 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. important!
  • 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.

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 parameter 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 🍪

okay so bestie, when this thing runs under mod_perl, it's gonna try to use Apache::Cookie first for all the cookie-handling. if that's not available? it falls back to CGI::Cookie. no cap.

if it ends up using CGI::Cookie, then you must hand it a header_object parameter. this object has to have an err_headers_out() or headers_out() method — it checks them in that exact order. that method is supposed to return an object with an API like Apache::Table. then it calls add() on whatever comes back to slap on a Set-Cookie header. 💅

🎀 REGISTERING CLASSES 🎀

so to support any Apache::Session subclasses, this module gives you a lil registration mechanism. you can register an Apache::Session subclass, or a class that's meant to provide a class implementing something required by Apache::Session::Flex. periodt.

✨ 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 these options, bestie:

  • name — this should be the name of the class you're registering. the actual class has to start with Apache::Session::, but that part doesn't need to be included when you register it (it's optional). slay.
  • required — these are the required parameters for this class. the value can either be a string or a reference to an array of array references. if it's a string, then it identifies an existing Apache::Session subclass that's already registered or built-in, like File or Postgres. if it's 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 gets constructed, only one of these sets has to 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 just be omitted. iconic.

  • optional — this specifies optional parameters, and it should just be a simple array reference. no biggie.

🦋 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. iykyk. 💖

🌈 SUBCLASSING 🌈

this class provides a simple hook for subclasses. before it tries 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 total no-op, but you can override it in a subclass. main character energy.

this class is a Class::Container subclass, so if you accept additional constructor parameters, you should declare them via the valid_params() method. don't forget, bestie.

💖 SUPPORT 💖

as you can see 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 (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.

💖 and that's the whole vibe, bestie — this page is from perl v5.34.0, dated 2022-06-06, and it's Apache...rapper(3pm). stay slay. ✨

📦 where this page comes from