NAME
    Mason::Plugin::PSGIHandler - PSGI handler for Mason

SYNOPSIS
        # Quick start:
        mason_psgi_setup myapp

        # app.psgi
        use Mason;
        use Plack::Builder;
        my $interp = Mason->new(
             plugins => ['PSGIHandler', ...],
             comp_root => '/path/to/comp_root/',
             data_dir => '/path/to/data_dir/',
        );
        my $app = sub {
            my $env = shift;
            $interp->handle_psgi($env);
        };
        builder {
            # Include PSGI middleware here
            $app;
        };

DESCRIPTION
    Provides a PSGI handler for Mason. It allows Mason to handle requests
    directly from any web servers that support PSGI.

  Run path
    The top-level run path is taken from the method Plack::Request. So in a
    simple Plack configuration like the one above, a URL like

        /foo/bar

    would result in

        $interp->run("/foo/bar");

    However, if you mounted your Mason app under "/mason",

        builder {
            mount "/mason" => builder {
                $app;
            };
            mount "/other" => $other_app;
            ...
        };

    then the "/mason" portion of the URL would get stripped off in the
    top-level run path.

  Run parameters
    The top-level run parameters are taken from the method Plack::Request,
    which combines GET and POST parameters. So

        /foo/bar?a=5&b=6

    would generally result in

        $interp->run("/foo/bar", a=>5, b=>6);

    If there are multiple values for a parameter, generally only the last
    value will be kept, as per Hash::MultiValue. However, if the
    corresponding attribute in the page component is declared an `ArrayRef',
    then all values will be kept and passed in as an arrayref. For example,
    if the page component `/foo/bar.mc' has these declarations:

        <%args>
        $.a
        $.b => (isa => "Int")
        $.c => (isa => "ArrayRef");
        $.d => (isa => "ArrayRef[Int]");
        </%args>

    then this URL

        /foo/bar?a=1&a=2&b=3&b=4&c=5&c=6&d=7&d=8

    would result in

        $interp->run("/foo/bar", a=>2, b=>4, c=>[5,6], d => [7,8]);

    You can always get the original Hash::MultiValue object from
    `$m->request_args'. e.g.

        my $hmv = $m->request_args;
        # get all values for 'e'
        $hmv->get_all('e');

  Plack request object
    A Mason::Plack::Request is constructed from the plack environment and
    made available in `$m->req'. This is a thin subclass of Plack::Request
    and provides information such as the URL and incoming HTTP headers. e.g.

        my $headers = $m->req->headers;
        my $cookie = $m->req->cookies->{'foo'};

  Plack response object
    An empty Mason::Plack::Response is constructed and made available in
    `$m->res'. Your Mason components are responsible for setting the status
    and headers, by calling `$m->res->status' and `$m->res->headers' or
    utility methods that do so. e.g.

        $m->res->content_type('text/plain');
        $m->res->cookies->{foo} = { value => 123 };

        $m->redirect('http://www.google.com/', 301)  # sets header/status and aborts
        $m->clear_and_abort(404);   # sets status and aborts

    If the Mason request finishes successfully, the Mason output becomes the
    plack response body; any value explicitly set in `$m->res->body' is
    ignored and overwritten. `$m->res->status' is set to 200 if it hasn't
    already been set.

    If the top-level component path cannot be found, `$m->res->status' is
    set to 404. All other runtime errors fall through to be handled by
    Plack, i.e. with Plack::Middleware::StackTrace in development mode or a
    500 error response in deployment mode.

INTERP METHODS
    handle_psgi ($env)
        Takes a PSGI environment hash, calls an appropriate Mason request as
        detailed above, and returns a standard PSGI response array.

REQUEST METHODS
    req ()
        A reference to the Mason::Plack::Request.

    res ()
        A reference to the Mason::Plack::Response.

    redirect (url[, status])
        Sets headers and status for redirect, then clears the Mason buffer
        and aborts the request. e.g.

            $m->redirect("http://somesite.com", 302);

        is equivalent to

            $m->res->redirect("http://somesite.com", 302);
            $m->clear_and_abort();

    not_found ()
        Sets the status to 404, then clears the Mason buffer and aborts the
        request. Equivalent to

            $m->res->status(404);
            $m->clear_and_abort();

    abort (status)
    clear_and_abort (status)
        These methods are overriden to set the response status before
        aborting, if *status* is provided. e.g. to send back a NOT FOUND
        result:

            $m->clear_and_abort(404);

        This is equivalent to

            $m->res->status(404);
            $m->clear_and_abort();

SUPPORT
    The mailing list for Mason and Mason plugins is
    mason-users@lists.sourceforge.net. You must be subscribed to send a
    message. To subscribe, visit
    https://lists.sourceforge.net/lists/listinfo/mason-users.

    You can also visit us at `#mason' on irc:.

    Bugs and feature requests will be tracked at RT:

        http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mason-Plugin-PSGIHandler
        bug-mason-plugin-psgihandler@rt.cpan.org

    The latest source code can be browsed and fetched at:

        http://github.com/jonswar/perl-mason-plugin-psgihandler
        git clone git://github.com/jonswar/perl-mason-plugin-psgihandler.git

SEE ALSO
    Mason, http://plackperl.org/