phpman > info > HTML::Mason::Request

HTML::Mason::Request(3User Contributed Perl DocumentaHTML::Mason::Request(3pm)

NAME
       HTML::Mason::Request - Mason Request Class

SYNOPSIS
           $m->abort (...)
           $m->comp (...)
           etc.

DESCRIPTION
       The Request API is your gateway to all Mason features not provided by
       syntactic tags. Mason creates a new Request object for every web
       request. Inside a component you access the current request object via
       the global $m.  Outside of a component, you can use the class method
       "instance".

COMPONENT PATHS
       The methods Request->comp, Request->comp_exists, and
       Request->fetch_comp take a component path argument.  Component paths
       are like URL paths, and always use a forward slash (/) as the
       separator, regardless of what your operating system uses.

       o   If the path is absolute (starting with a '/'), then the component
           is found relative to the component root.

       o   If the path is relative (no leading '/'), then the component is
           found relative to the current component directory.

       o   If the path matches both a subcomponent and file-based component,
           the subcomponent takes precedence.

PARAMETERS TO THE new() CONSTRUCTOR
       autoflush
           True or false, default is false. Indicates whether to flush the
           output buffer ("$m->flush_buffer") after every string is output.
           Turn on autoflush if you need to send partial output to the client,
           for example in a progress meter.

           As of Mason 1.3, autoflush will only work if enable_autoflush has
           been set.  Components can be compiled more efficiently if they
           don't have to check for autoflush. Before using autoflush you might
           consider whether a few manual "$m->flush_buffer" calls would work
           nearly as well.

       data_cache_api
           The "$m->cache" API to use:

           o   '1.1', the default, indicates a "Cache::Cache" based API.

           o   'chi' indicates a "CHI" based API.

           o   '1.0' indicates the custom cache API used in Mason 1.0x and
               earlier. This compatibility layer is provided as a convenience
               for users upgrading from older versions of Mason, but will not
               be supported indefinitely.

       data_cache_defaults
           A hash reference of default options to use for the "$m->cache"
           command.  For example, to use Cache::Cache's "MemoryCache"
           implementation by default:

               data_cache_defaults => {cache_class => 'MemoryCache'}

           To use the CHI "FastMmap" driver by default:

               data_cache_api      => 'CHI',
               data_cache_defaults => {driver => 'FastMmap'},

           These settings are overridden by options given to particular
           "$m->cache" calls.

       dhandler_name
           File name used for dhandlers. Default is "dhandler".  If this is
           set to an empty string ("") then dhandlers are turned off entirely.

       error_format
           Indicates how errors are formatted. The built-in choices are

           o   brief - just the error message with no trace information

           o   text - a multi-line text format

           o   line - a single-line text format, with different pieces of
               information separated by tabs (useful for log files)

           o   html - a fancy html format

           The default format under Apache and CGI is either line or html
           depending on whether the error mode is fatal or output,
           respectively. The default for standalone mode is text.

           The formats correspond to "HTML::Mason::Exception" methods named
           as_format. You can define your own format by creating an
           appropriately named method; for example, to define an "xml" format,
           create a method "HTML::Mason::Exception::as_xml" patterned after
           one of the built-in methods.

       error_mode
           Indicates how errors are returned to the caller.  The choices are
           fatal, meaning die with the error, and output, meaning output the
           error just like regular output.

           The default under Apache and CGI is output, causing the error to be
           displayed in the browser.  The default for standalone mode is
           fatal.

       component_error_handler
           A code reference used to handle errors thrown during component
           compilation or runtime. By default, this is a subroutine that turns
           non-exception object errors in components into exceptions. If this
           parameter is set to a false value, these errors are simply rethrown
           as-is.

           Turning exceptions into objects can be expensive, since this will
           cause the generation of a stack trace for each error. If you are
           using strings or unblessed references as exceptions in your code,
           you may want to turn this off as a performance boost.

       max_recurse
           The maximum recursion depth for the component stack, for the
           request stack, and for the inheritance stack. An error is signalled
           if the maximum is exceeded.  Default is 32.

       out_method
           Indicates where to send output. If out_method is a reference to a
           scalar, output is appended to the scalar.  If out_method is a
           reference to a subroutine, the subroutine is called with each
           output string. For example, to send output to a file called
           "mason.out":

               my $fh = new IO::File ">mason.out";
               ...
               out_method => sub { $fh->print($_[0]) }

           By default, out_method prints to standard output. Under Apache,
           standard output is redirected to "$r->print".

       plugins
           An array of plugins that will be called at various stages of
           request processing.  Please see HTML::Mason::Plugin for details.

ACCESSOR METHODS
       All of the above properties have standard accessor methods of the same
       name. In general, no arguments retrieves the value, and one argument
       sets and returns the value.  For example:

           my $max_recurse_level = $m->max_recurse;
           $m->autoflush(1);

OTHER METHODS
       abort ([return value])
           Ends the current request, finishing the page without returning
           through components. The optional argument specifies the return
           value from "Interp::exec"; in a web environment, this ultimately
           becomes the HTTP status code.

           "abort" is implemented by throwing an HTML::Mason::Exception::Abort
           object and can thus be caught by eval(). The "aborted" method is a
           shortcut for determining whether a caught error was generated by
           "abort".

           If "abort" is called from a component that has a "<%filter>", than
           any output generated up to that point is filtered, unless "abort"
           is called from a "<%shared>" block.

       clear_and_abort ([return value])
           This method is syntactic sugar for calling "clear_buffer()" and
           then "abort()".  If you are aborting the request because of an
           error, you will often want to clear the buffer first so that any
           output generated up to that point is not sent to the client.

       aborted ([$err])
           Returns true or undef indicating whether the specified $err was
           generated by "abort". If no $err was passed, uses $@.

           In this code, we catch and process fatal errors while letting
           "abort" exceptions pass through:

               eval { code_that_may_fail_or_abort() };
               if ($@) {
                   die $@ if $m->aborted;

                   # handle fatal errors...

           $@ can lose its value quickly, so if you are planning to call
           $m->aborted more than a few lines after the eval, you should save
           $@ to a temporary variable.

       base_comp
           Returns the current base component.

           Here are the rules that determine base_comp as you move from
           component to component.

           o   At the beginning of a request, the base component is
               initialized to the requested component ("$m->request_comp()").

           o   When you call a regular component via a path, the base
               component changes to the called component.

           o   When you call a component method via a path (/foo/bar:baz), the
               base component changes to the method's owner.

           o   The base component does not change when:

               o   a component call is made to a component object

               o   a component call is made to SELF:x or PARENT:x or REQUEST:x

               o   a component call is made to a subcomponent (<%def>)

           This may return nothing if the base component is not yet known, for
           example inside a plugin's "start_request_hook()" method, where we
           have created a request but it does not yet know anything about the
           component being called.

       cache
           "$m->cache" returns a new cache object with a namespace specific to
           this component. The parameters to and return value from "$m->cache"
           differ depending on which data_cache_api you are using.

           If data_cache_api = 1.1 (default)
               cache_class specifies the class of cache object to create. It
               defaults to "FileCache" in most cases, or "MemoryCache" if the
               interpreter has no data directory, and must be a backend
               subclass of "Cache::Cache". The prefix "Cache::" need not be
               included.  See the "Cache::Cache" package for a full list of
               backend subclasses.

               Beyond that, cache_options may include any valid options to the
               new() method of the cache class. e.g. for "FileCache", valid
               options include "default_expires_in" and "cache_depth".

               See HTML::Mason::Cache::BaseCache for information about the
               object returned from "$m->cache".

           If data_cache_api = CHI
               chi_root_class specifies the factory class that will be called
               to create cache objects. The default is 'CHI'.

               driver specifies the driver to use, for example "Memory" or
               "FastMmap".  The default is "File" in most cases, or "Memory"
               if the interpreter has no data directory.

               Beyond that, cache_options may include any valid options to the
               new() method of the driver. e.g. for the "File" driver, valid
               options include "expires_in" and "depth".

       cache_self ([expires_in => '...'], [key => '...'], [get_options],
       [cache_options])
           "$m->cache_self" caches the entire output and return result of a
           component.

           "cache_self" either returns undef, or a list containing the return
           value of the component followed by '1'. You should return
           immediately upon getting the latter result, as this indicates that
           you are inside the second invocation of the component.

           "cache_self" takes any of parameters to "$m->cache" (e.g.
           cache_depth), any of the optional parameters to "$cache->get"
           (expire_if, busy_lock), and two additional options:

           o   expire_in or expires_in: Indicates when the cache expires - it
               is passed as the third argument to "$cache->set". e.g. '10
               sec', '5 min', '2 hours'.

           o   key: An identifier used to uniquely identify the cache results
               - it is passed as the first argument to "$cache->get" and
               "$cache->set".  The default key is '__mason_cache_self__'.

           To cache the component's output:

               <%init>
               return if $m->cache_self(expire_in => '10 sec'[, key => 'fookey']);
               ... <rest of init> ...
               </%init>

           To cache the component's scalar return value:

               <%init>
               my ($result, $cached) = $m->cache_self(expire_in => '5 min'[, key => 'fookey']);

               return $result if $cached;
               ... <rest of init> ...
               </%init>

           To cache the component's list return value:

               <%init>
               my (@retval) = $m->cache_self(expire_in => '3 hours'[, key => 'fookey']);

               return @retval if pop @retval;
               ... <rest of init> ...
               </%init>

           We call "pop" on @retval to remove the mandatory '1' at the end of
           the list.

           If a component has a "<%filter>" block, then the filtered output is
           cached.

           Note: users upgrading from 1.0x and earlier can continue to use the
           old "$m->cache_self" API by setting data_cache_api to '1.0'.  This
           support will be removed at a later date.

           See the the DATA CACHING section of the developer's manual section
           for more details on how to exercise finer control over caching.

       caller_args
           Returns the arguments passed by the component at the specified
           stack level. Use a positive argument to count from the current
           component and a negative argument to count from the component at
           the bottom of the stack. e.g.

               $m->caller_args(0)   # arguments passed to current component
               $m->caller_args(1)   # arguments passed to component that called us
               $m->caller_args(-1)  # arguments passed to first component executed

           When called in scalar context, a hash reference is returned.  When
           called in list context, a list of arguments (which may be assigned
           to a hash) is returned.  Returns undef or an empty list, depending
           on context, if the specified stack level does not exist.

       callers
           With no arguments, returns the current component stack as a list of
           component objects, starting with the current component and ending
           with the top-level component. With one numeric argument, returns
           the component object at that index in the list. Use a positive
           argument to count from the current component and a negative
           argument to count from the component at the bottom of the stack.
           e.g.

               my @comps = $m->callers   # all components
               $m->callers(0)            # current component
               $m->callers(1)            # component that called us
               $m->callers(-1)           # first component executed

           Returns undef or an empty list, depending on context, if the
           specified stack level does not exist.

       caller
           A synonym for "$m->callers(1)", i.e. the component that called the
           currently executing component.

       call_next ([args...])
           Calls the next component in the content wrapping chain; usually
           called from an autohandler. With no arguments, the original
           arguments are passed to the component.  Any arguments specified
           here serve to augment and override (in case of conflict) the
           original arguments. Works like "$m->comp" in terms of return value
           and scalar/list context.  See the autohandlers section of the
           developer's manual for examples.

       call_self (output, return, error, tag)
           This method allows a component to call itself so that it can filter
           both its output and return values.  It is fairly advanced; for most
           purposes the "<%filter>" tag will be sufficient and simpler.

           "$m->call_self" takes four arguments, all of them optional.

           output - scalar reference that will be populated with the component
           output.
           return - scalar reference that will be populated with the component
           return value.
           error - scalar reference that will be populated with the error
           thrown by the component, if any. If this parameter is not defined,
           then call_self will not catch errors.
           tag - a name for this call_self invocation; can almost always be
           omitted.

           "$m->call_self" acts like a "fork()" in the sense that it will
           return twice with different values.  When it returns 0, you allow
           control to pass through to the rest of your component.  When it
           returns 1, that means the component has finished and you can
           examine the output, return value and error. (Don't worry, it
           doesn't really do a fork! See next section for explanation.)

           The following examples would generally appear at the top of a
           "<%init>" section.  Here is a no-op "$m->call_self" that leaves the
           output and return value untouched:

               <%init>
               my ($output, $retval);
               if ($m->call_self(\$output, \$retval)) {
                   $m->print($output);
                   return $retval;
               }
               ...

           Here is a simple output filter that makes the output all uppercase.
           Note that we ignore both the original and the final return value.

               <%init>
               my ($output, $error);
               if ($m->call_self(\$output, undef)) {
                   $m->print(uc $output);
                   return;
               }
               ...

           Here is a piece of code that traps all errors occurring anywhere in
           a component or its children, e.g. for the purpose of handling
           application-specific exceptions. This is difficult to do with a
           manual "eval" because it would have to span multiple code sections
           and the main component body.

               <%init>
               my ($output, undef, $error);
               if ($m->call_self(\$output, undef, \$error)) {
                   if ($error) {
                       # check $error and do something with it
                   }
                   $m->print($output);
                   return;
               }
               ...

       clear_buffer
           Clears the Mason output buffer. Any output sent before this line is
           discarded. Useful for handling error conditions that can only be
           detected in the middle of a request.

           clear_buffer is, of course, thwarted by "flush_buffer".

       comp (comp, args...)
           Calls the component designated by comp with the specified
           option/value pairs. comp may be a component path or a component
           object.

           Components work exactly like Perl subroutines in terms of return
           values and context. A component can return any type of value, which
           is then returned from the "$m->comp" call.

           The <& &> tag provides a convenient shortcut for "$m->comp".

           As of 1.10, component calls can accept an initial hash reference of
           modifiers.  The only currently supported modifier is "store", which
           stores the component's output in a scalar reference. For example:

             my $buf;
             my $return = $m->comp( { store => \$buf }, '/some/comp', type => 'big' );

           This mostly duplicates the behavior of scomp, but can be useful in
           rare cases where you need to capture both a component's output and
           return value.

           This modifier can be used with the <& &> tag as well, for example:

             <& { store => \$buf }, '/some/comp', size => 'medium' &>

       comp_exists (comp_path)
           Returns 1 if comp_path is the path of an existing component, 0
           otherwise.  comp_path may be any path accepted by comp or
           fetch_comp, including method or subcomponent paths.

           Depending on implementation, <comp_exists> may try to load the
           component referred to by the path, and may throw an error if the
           component contains a syntax error.

       content
           Evaluates the content (passed between <&| comp &> and </&> tags) of
           the current component, and returns the resulting text.

           Returns undef if there is no content.

       has_content
           Returns true if the component was called with content (i.e. with
           <&| comp &> and </&> tags instead of a single <& comp &> tag). This
           is generally better than checking the defined'ness of "$m->content"
           because it will not try to evaluate the content.

       count
           Returns the number of this request, which is unique for a given
           request and interpreter.

       current_args
           Returns the arguments passed to the current component. When called
           in scalar context, a hash reference is returned.  When called in
           list context, a list of arguments (which may be assigned to a hash)
           is returned.

       current_comp
           Returns the current component object.

       decline
           Used from a top-level component or dhandler, this method clears the
           output buffer, aborts the current request and restarts with the
           next applicable dhandler up the tree. If no dhandler is available,
           a not-found error occurs.

           This method bears no relation to the Apache DECLINED status except
           in name.

       declined ([$err])
           Returns true or undef indicating whether the specified $err was
           generated by "decline". If no $err was passed, uses $@.

       depth
           Returns the current size of the component stack.  The lowest
           possible value is 1, which indicates we are in the top-level
           component.

       dhandler_arg
           If the request has been handled by a dhandler, this method returns
           the remainder of the URI or "Interp::exec" path when the dhandler
           directory is removed. Otherwise returns undef.

           "dhandler_arg" may be called from any component in the request, not
           just the dhandler.

       exec (comp, args...)
           Starts the request by executing the top-level component and
           arguments. This is normally called for you on the main request, but
           you can use it to execute subrequests.

           A request can only be executed once; e.g. it is an error to call
           this recursively on the same request.

       fetch_comp (comp_path)
           Given a comp_path, returns the corresponding component object or
           undef if no such component exists.

       fetch_next
           Returns the next component in the content wrapping chain, or undef
           if there is no next component. Usually called from an autohandler.
           See the autohandlers section of the developer's manual for usage
           and examples.

       fetch_next_all
           Returns a list of the remaining components in the content wrapping
           chain. Usually called from an autohandler.  See the autohandlers
           section of the developer's manual for usage and examples.

       file (filename)
           Returns the contents of filename as a string. If filename is a
           relative path, Mason prepends the current component directory.

       flush_buffer
           Flushes the Mason output buffer. Under mod_perl, also sends HTTP
           headers if they haven't been sent and calls "$r->rflush" to flush
           the Apache buffer. Flushing the initial bytes of output can make
           your servers appear more responsive.

           Attempts to flush the buffers are ignored within the context of a
           call to "$m->scomp" or when output is being stored in a scalar
           reference, as with the " { store => \$out } " component call
           modifier.

           "<%filter>" blocks will process the output whenever the buffers are
           flushed.  If "autoflush" is on, your data may be filtered in small
           pieces.

       instance
           This class method returns the "HTML::Mason::Request" currently in
           use.  If called when no Mason request is active it will return
           "undef".

           If called inside a subrequest, it returns the subrequest object.

       interp
           Returns the Interp object associated with this request.

       make_subrequest (comp => path, args => arrayref, other parameters)
           This method creates a new Request object which inherits its
           parent's settable properties, such as autoflush and out_method.
           These values may be overridden by passing parameters to this
           method.

           The "comp" parameter is required, while all other parameters are
           optional.  It may be specified as an absolute path or as a path
           relative to the current component.

           See the subrequests section of the developer's manual for more
           information about subrequests.

       log Returns a "Log::Any" logger with a log category specific to the
           current component.  The category for a component "/foo/bar" would
           be "HTML::Mason::Component::foo::bar".

       notes (key, value)
           The "notes()" method provides a place to store application data,
           giving developers a way to share data among multiple components.
           Any data stored here persists for the duration of the request, i.e.
           the same lifetime as the Request object.

           Conceptually, "notes()" contains a hash of key-value pairs.
           "notes($key, $value)" stores a new entry in this hash.
           "notes($key)" returns a previously stored value.  "notes()" without
           any arguments returns a reference to the entire hash of key-value
           pairs.

           "notes()" is similar to the mod_perl method "$r->pnotes()".  The
           main differences are that this "notes()" can be used in a
           non-mod_perl environment, and that its lifetime is tied to the
           Mason request object, not the Apache request object.  In
           particular, a Mason subrequest has its own "notes()" structure, but
           would access the same "$r->pnotes()" structure.

       out (string)
           A synonym for "$m->print".

       print (string)
           Print the given string. Rarely needed, since normally all text is
           just placed in the component body and output implicitly.
           "$m->print" is useful if you need to output something in the middle
           of a Perl block.

           In 1.1 and on, "print" and "$r->print" are remapped to "$m->print",
           so they may be used interchangeably. Before 1.1, one should only
           use "$m->print".

       request_args
           Returns the arguments originally passed to the top level component
           (see request_comp for definition).  When called in scalar context,
           a hash reference is returned. When called in list context, a list
           of arguments (which may be assigned to a hash) is returned.

       request_comp
           Returns the component originally called in the request. Without
           autohandlers, this is the same as the first component executed.
           With autohandlers, this is the component at the end of the
           "$m->call_next" chain.

       request_depth
           Returns the current size of the request/subrequest stack.  The
           lowest possible value is 1, which indicates we are in the top-level
           request.  A value of 2 indicates we are inside a subrequest of the
           top-level request, and so on.

       scomp (comp, args...)
           Like comp, but returns the component output as a string instead of
           printing it. (Think sprintf versus printf.) The component's return
           value is discarded.

       subexec (comp, args...)
           This method creates a new subrequest with the specified top-level
           component and arguments, and executes it. This is most often used
           to perform an "internal redirect" to a new component such that
           autohandlers and dhandlers take effect.

       time
           Returns the interpreter's notion of the current time (deprecated).

APACHE-ONLY METHODS
       These additional methods are available when running Mason with mod_perl
       and the ApacheHandler.

       ah  Returns the ApacheHandler object associated with this request.

       apache_req
           Returns the Apache request object.  This is also available in the
           global $r.

       auto_send_headers
           True or false, default is true.  Indicates whether Mason should
           automatically send HTTP headers before sending content back to the
           client. If you set to false, you should call "$r->send_http_header"
           manually.

           See the sending HTTP headers section of the developer's manual for
           more details about the automatic header feature.

           NOTE: This parameter has no effect under mod_perl-2, since calling
           "$r->send_http_header" is no longer needed.

CGI-ONLY METHODS
       This additional method is available when running Mason with the
       CGIHandler module.

       cgi_request
           Returns the Apache request emulation object, which is available as
           $r inside components.

           See the CGIHandler docs for more details.

APACHE- OR CGI-ONLY METHODS
       This method is available when Mason is running under either the
       ApacheHandler or CGIHandler modules.

       cgi_object
           Returns the CGI object used to parse any CGI parameters submitted
           to the component, assuming that you have not changed the default
           value of the ApacheHandler args_method parameter.  If you are using
           the 'mod_perl' args method, then calling this method is a fatal
           error.  See the ApacheHandler and CGIHandler documentation for more
           details.

       redirect ($url, [$status])
           Given a url, this generates a proper HTTP redirect for that URL. It
           uses "$m->clear_and_abort" to clear out any previous output, and
           abort the request.  By default, the status code used is 302, but
           this can be overridden by the user.

           Since this is implemented using "$m->abort", it will be trapped by
           an " eval {} " block.  If you are using an " eval {} " block in
           your code to trap errors, you need to make sure to rethrow these
           exceptions, like this:

             eval {
                 ...
             };

             die $@ if $m->aborted;

             # handle other exceptions

perl v5.30.2                      2020-05-22         HTML::Mason::Request(3pm)