HTML::...andler(3pm)

💖 HTML::Mason::ApacheHandler — Mason/mod_perl interface 💖

okay bestie, gather round, because this is the page that glues Mason to mod_perl and honestly? iconic. it's HTML::Mason::ApacheHandler, and it's your ride-or-die for serving components over HTTP. 🦋

---

✨ SYNOPSIS ✨

use HTML::Mason::ApacheHandler;

my $ah = HTML::Mason::ApacheHandler->new (..name/value params..);
...
sub handler {
    my $r = shift;
    $ah->handle_request($r);
}

that's it. that's the whole vibe. 💅

---

🌸 DESCRIPTION 🌸

so the ApacheHandler object is literally the bridge between Mason and mod_perl (version 1 or 2, she does both, versatile queen), running components in response to HTTP requests. and the way you steer her? mostly through the params you hand to the new() constructor. no cap. ✨

---

🎀 PARAMETERS TO THE new() CONSTRUCTOR 🎀

• apache_status_title — the title you want this ApacheHandler to show up as under Apache::Status. the default is "HTML::Mason status". super useful when you've got more than one ApacheHandler object and you want all of them visible via Apache::Status — like a little friend group in the status page 🫶
• args_method — the method used for unpacking GET and POST arguments. the valid options are 'CGI' and 'mod_perl'; these mean a "CGI.pm" or "Apache::Request" object (respectively) gets created for the purposes of argument handling. 👑

'mod_perl' is the default under mod_perl-1, and it requires that you have installed the "Apache::Request" package. under mod_perl-2, the default is 'CGI' because "Apache2::Request" is still in development. (she's growing, give her time 😭)

if args_method is 'mod_perl', the $r global gets upgraded to an Apache::Request object. this object inherits all Apache methods and adds a few of its own, dealing with parameters and file uploads. see "Apache::Request" for more info.

if the args_method is 'CGI', the Mason request object ($m) will have a method called "cgi_object" available. that method returns the CGI object used for argument processing.

and listen — while Mason will load "Apache::Request" or "CGI" as needed at runtime, it is recommended that you preload the relevant module either in your httpd.conf or handler.pl file, because that saves some memory. lowkey free real estate. 💖

• decline_dirs — true or false, default is true. indicates whether Mason should decline directory requests, leaving Apache to serve up a directory index or a "FORBIDDEN" error as appropriate. see the allowing directory requests section of the administrator's manual for more about handling directories with Mason.
• interp — the interpreter object to associate with this compiler. by default a new object of the specified interp_class will be created.
• interp_class — the class to use when creating a interpreter. defaults to HTML::Mason::Interp.

---

💅 ACCESSOR METHODS 💅

all of the above properties, except interp_class, have standard accessor methods of the same name: no arguments retrieves the value, and one argument sets it — except for args_method, which is not settable. periodt. 🔥

for example:

my $ah = HTML::Mason::ApacheHandler->new;
my $decline_dirs = $ah->decline_dirs;
$ah->decline_dirs(1);

look at her go. 🎀

---

🌈 OTHER METHODS 🌈

the ApacheHandler object has a few other publicly accessible methods that may be of interest to end users. main character energy only.

• handle_request ($r) — this method takes an Apache or Apache::Request object representing a request and translates that request into a form Mason can understand. its return value is an Apache status code.

passing an Apache::Request object is useful if you want to set Apache::Request parameters, such as POST_MAX or DISABLE_UPLOADS. 🫶

• prepare_request ($r) — this method takes an Apache object representing a request and returns a new Mason request object or an Apache status code. if it is a request object you can manipulate that object as you like, and then call the request object's "exec" method to have it generate output.

if this method returns an Apache status code, that means that it could not create a Mason request object. 💀

this method is useful if you would like to have a chance to decline a request based on properties of the Mason request object or a component object. for example:

my $req = $ah->prepare_request($r);
# $req must be an Apache status code if it's not an object
return $req unless ref($req);

return DECLINED
    unless $req->request_comp->source_file =~ /\.html$/;

$req->exec;

• request_args ($r) — given an Apache request object, this method returns a three item list. the first item is a hash reference containing the arguments passed by the client's request.

the second is an Apache request object. this is returned for backwards compatibility from when this method was responsible for turning a plain Apache object into an Apache::Request object. (nostalgia era 🥺)

the third item may be a CGI.pm object or "undef", depending on the value of the args_method parameter.

---

ngl this page is from User Contributed Perl Documentation, she's running on perl v5.38.2, dated 2024-03-05, and she's filed under HTML::...andler(3pm). iykyk. slay, bestie, go serve some components 💖✨🌸🦋