HTML::Mason::Plugin - phpMan

NAME
    HTML::Mason::Plugin - Plugin Base class for Mason

SYNOPIS
       package MasonX::Plugin::Timer;
       use base qw(HTML::Mason::Plugin);
       use Time::HiRes;

       sub start_component_hook {
           my ($self, $context) = @_;
           push @{$self->{ timers }}, Time::HiRes::time;
       }

       sub end_component_hook {
           my ($self, $context) = @_;
           my $elapsed = Time::HiRes::time - pop @{$self->{ timers }};
           printf STDERR "Component '%s' took %.1f seconds\n",
               $context->comp->title, $elapsed;
       }

       1;

DESCRIPTION
    Use a Mason plugin to have actions occur at the beginning or end of
    requests or components. Plugins are activated by passing plugins in the
    interpreter or request object. Each plugin in the list can be specified
    as a class name (in which case the plugin object is created once for
    each request) or as an actual object of the plugin class.

    If your plugin can be configured, place the configuration in class
    variables - for example,

        $MasonX::Plugin::Timer::Units = 'seconds';

    These can be set either from httpd.conf via PerlSetVar directives, or in
    perl directly from a handler.pl file.

PLUGIN HOOKS
    A plugin class defines one or more of the following hooks (methods):
    *start_request_hook*, *end_request_hook*, *start_component_hook*, and
    *end_component_hook*.

    Every hook receives two arguments: the plugin object itself, and a
    context object with various methods.

    start_request_hook
        "start_request_hook" is called before the Mason request begins
        execution. Its context has the following read-only methods:

            request # the current request ($m)
            args    # arguments the request was called with

        When called in scalar context, *args* returns a list reference which
        may be modified to change or add to the arguments passed to the
        first component. When called in list context, *args* returns a list
        (which may be assigned to a hash).

        Note that subrequests (see HTML::Mason::Request will create a new
        plugin object and execute this code again; you can skip your code
        for subrequests by checking "is_subrequest" on *request*. e.g.

           sub start_request_hook {
               my ($self, $context) = @_;
               unless ($context->request->is_subrequest()) {
                   # perform hook action
               }
           }

        Currently, this hook is called before any information about the
        requested component is available, so you cannot call methods like
        "base_comp()" or "request_args()" on the Request object.

    end_request_hook
        "end_request_hook" is called before the Mason request exits. Its
        context has the following read-only methods:

            request     # the current request ($m)
            args        # arguments the request was called with
            output      # reference to the contents of the output buffer
            wantarray   # value of wantarray the request was called with
            result      # arrayref of value(s) that the request is about to return
            error       # reference to error, if any, that the request is about to throw

        When called in scalar context, *args* returns a list reference; when
        called in list context, it returns a list (which may be assigned to
        a hash).

        *result* always contains an array ref; if *wantarray* is 0, the
        return value is the the first element of that array. The plugin may
        modify *output* to affect what the request outputs, and *result* and
        *error* to affect what the request returns.

    start_component_hook
        "start_component_hook" is called before a component begins
        executing. Its context has the following read-only methods:

            request     # the current request ($m)
            comp        # the component object
            args        # arrayref of arguments the component was called with

        The plugin may NOT modify *args* currently.

    end_component_hook
        "end_component_hook()" is called after a component has completed.
        Its context has the following read-only methods:

            request     # the current request ($m)
            comp        # the component object
            args        # arrayref of arguments the component was called with
            wantarray   # value of wantarray the component was called with
            result      # arrayref of value(s) that the component is about to return
            error       # reference to error, if any, that the component is about to throw

        *result* always contains an array ref; if *wantarray* is 0, the
        return value is the first element of that array. The plugin may
        modify both *result* and *error* to affect how the request returns.

        It would be desirable for this hook to have access to the
        component's output as well as its return value, but this is
        currently impossible because output from multiple components combine
        into a single buffer.

WARNINGS
    Do not keep an unweakened reference to a request or component object in
    your plugin object, or you will create a nasty circular reference.