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]"); 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/