MasonX...ession(3pm)

✨ MasonX::Request::WithApacheSession ✨

okay bestie, pull up a chair 💖 this is the manual page (a 3pm one, Perl module vibes) for MasonX::Request::WithApacheSession — the little glue guy that bolts a session onto your Mason Request object. no cap.

---

🎀 NAME 🎀

MasonX::Request::WithApacheSession — adds a session to the Mason Request object. that's it, that's the whole job 💅

---

🌸 SYNOPSIS 🌸

first up, if you're living your life in your httpd.conf file:

PerlSetVar  MasonRequestClass            MasonX::Request::WithApacheSession
PerlSetVar  MasonSessionCookieDomain     .example.com
PerlSetVar  MasonSessionClass            Apache::Session::File
PerlSetVar  MasonSessionDirectory        /tmp/sessions/data
PerlSetVar  MasonSessionLockDirectory    /tmp/sessions/locks

or, alternative route, when you're creating an ApacheHandler object:

my $ah =
    HTML::Mason::ApacheHandler->new
        ( request_class => 'MasonX::Request::WithApacheSession',
          session_cookie_domain  => '.example.com',
          session_class          => 'Apache::Session::File',
          session_directory      => '/tmp/sessions/data',
          session_lock_directory => '/tmp/sessions/locks',
        );

and inside an actual component, the moment you've been waiting for:

$m->session->{foo} = 1;
if ( $m->session->{bar}{baz} > 1 ) { ... }

it's giving effortless. it's giving $m->session just exists now 🦋

---

🌈 DESCRIPTION 🌈

so this module integrates Apache::Session into Mason by adding methods to the Mason Request object — and those methods are available in all Mason components. every single one. no gatekeeping.

and here's the cute part: any subrequests created by a request share the same session. yes bestie, the vibes carry through the whole subrequest tree 🙈

---

💜 USAGE 💜

to use this module you need to tell Mason to use this class for requests. two ways to do it, pick your fighter.

Option 1 — you're configuring Mason via your httpd.conf file, so just add this:

PerlSetVar  MasonRequestClass  MasonX::Request::WithApacheSession

Option 2 — you're using a handler.pl file, so just add this parameter to the parameters you hand to the ApacheHandler constructor:

request_class => 'MasonX::Request::WithApacheSession'

that's it. that's the setup. slay ✨

---

👑 METHODS 👑

this class adds two methods to the Request object. two. a duo. a main-character-and-their-bestie situation.

• session — returns a hash tied to the Apache::Session class. yes, a whole tied hash. iconic.
• delete_session — deletes the existing session from persistent storage. and if you're using the built-in cookie mechanism, it also deletes the cookie in the browser. so it's a full clean-out, not a half one 💅

---

🧚 CONFIGURATION 🧚

ngl, this module accepts quite a number of parameters — and most of them are just getting passed straight through to Apache::Session::Wrapper. so before you start configuring this thing, you are advised to familiarize yourself with the Apache::Session::Wrapper documentation. that's not me being dramatic, that's literally in the docs. do your reading, bestie 📚

how the naming works

if you're creating your own Interp/ApacheHandler/CGIHandler object in a script or module, you should pass this object the parameters intended for Apache::Session::Wrapper, but prefixed with session_. so to set the class parameter for Apache::Session::Wrapper, you pass in a session_class parameter. easy.

if you're configuring Mason via your httpd.conf file, you pass the StudlyCaps version of the name, prefixed by MasonSession. so the class parameter would be MasonSessionClass.

a few examples, since examples are everything:

• class becomes session_class / MasonSessionClass
• always_write becomes session_always_write / MasonSessionAlwaysWrite

the automatic stuff 🔥

when running under ApacheHandler or CGIHandler, this module takes care of passing the header_object and param_object parameters to Apache::Session::Wrapper. these will be the Apache::Request or CGI.pm objects, as applicable. you don't have to lift a finger 💅

the cookie_name parameter defaults to MasonX-Request-WithApacheSession-cookie when you use this module, instead of Apache-Session-Wrapper-cookie. noting that, because defaults matter.

for the OGs 👵

finally, for backwards compatiblity, this module accepts a session_args_param parameter, which corresponds to the param_name parameter for Apache::Session::Wrapper. keeping the legacy alive, respectfully.

---

💀 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. which means there are almost certainly bugs. not me being ominous, that's just the truth 😭

bug reports and requests for help should be sent to the mason-users list. see http://www.masonhq.com/resources/mailing_lists.html for more details. go forth and report 🫶

---

⭐ AUTHOR ⭐

Dave Rolsky, <autarch@urth.org>

🌟 MAINTAINER 🌟

Brad Lhotsky, <blhotsky@cpan.org>

🔍 SEE ALSO 🔍

• HTML::Mason

---

okay that's the whole page, you're fully caught up 💖 this was the User Contributed Perl Documentation version of the MasonX::Request::WithApacheSession manual, running perl v5.36.0, dated 2022-10-13 — go forth, session responsibly, and remember: any subrequests share the same session, so don't be weird about it 🌈✨👑