NAME

       HTML::Mason::ApacheHandler - Mason/mod_perl interface

SYNOPSIS

           use HTML::Mason::ApacheHandler;

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

DESCRIPTION

       The ApacheHandler object links Mason to mod_perl (version 1 or 2), running components in response to HTTP
       requests. It is controlled primarily through parameters to the new() constructor.

PARAMETERS TO THE new() CONSTRUCTOR

       apache_status_title
           Title  that  you  want this ApacheHandler to appear as under Apache::Status.  Default is "HTML::Mason
           status".  This is useful if you create more than one ApacheHandler object and want them  all  visible
           via Apache::Status.

       args_method
           Method to use for unpacking GET and POST arguments. The valid options are 'CGI' and 'mod_perl'; these
           indicate  that a "CGI.pm" or "Apache::Request" object (respectively) will be created for the purposes
           of argument handling.

           'mod_perl' is the default under mod_perl-1 and requires that you have installed the "Apache::Request"
           package.  Under mod_perl-2, the default is 'CGI' because "Apache2::Request" is still in development.

           If args_method is 'mod_perl', the $r global is 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 information.

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

           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, as this will save some
           memory.

       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  information  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.
       For example:

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

OTHER METHODS

       The ApacheHandler object has a few other publicly accessible methods that  may  be  of  interest  to  end
       users.

       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.

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

perl v5.38.2                                       2024-03-05                    HTML::Mason::ApacheHandler(3pm)