.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.26)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Plack::Request 3pm"
.TH Plack::Request 3pm "2014-04-05" "perl v5.14.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Plack::Request \- Portable HTTP request object from PSGI env hash
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Plack::Request;
\&
\&  my $app_or_middleware = sub {
\&      my $env = shift; # PSGI env
\&
\&      my $req = Plack::Request\->new($env);
\&
\&      my $path_info = $req\->path_info;
\&      my $query     = $req\->param(\*(Aqquery\*(Aq);
\&
\&      my $res = $req\->new_response(200); # new Plack::Response
\&      $res\->finalize;
\&  };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Plack::Request provides a consistent \s-1API\s0 for request objects across
web server environments.
.SH "CAVEAT"
.IX Header "CAVEAT"
Note that this module is intended to be used by Plack middleware
developers and web application framework developers rather than
application developers (end users).
.PP
Writing your web application directly using Plack::Request is
certainly possible but not recommended: it's like doing so with
mod_perl's Apache::Request: yet too low level.
.PP
If you're writing a web application, not a framework, then you're
encouraged to use one of the web application frameworks that support \s-1PSGI\s0 (<http://plackperl.org/#frameworks>),
or see modules like HTTP::Engine to provide higher level
Request and Response \s-1API\s0 on top of \s-1PSGI\s0.
.SH "METHODS"
.IX Header "METHODS"
Some of the methods defined in the earlier versions are deprecated in
version 0.99. Take a look at \*(L"\s-1INCOMPATIBILITIES\s0\*(R".
.PP
Unless otherwise noted, all methods and attributes are \fBread-only\fR,
and passing values to the method like an accessor doesn't work like
you expect it to.
.SS "new"
.IX Subsection "new"
.Vb 1
\&    Plack::Request\->new( $env );
.Ve
.PP
Creates a new request object.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.IP "env" 4
.IX Item "env"
Returns the shared \s-1PSGI\s0 environment hash reference. This is a
reference, so writing to this environment passes through during the
whole \s-1PSGI\s0 request/response cycle.
.IP "address" 4
.IX Item "address"
Returns the \s-1IP\s0 address of the client (\f(CW\*(C`REMOTE_ADDR\*(C'\fR).
.IP "remote_host" 4
.IX Item "remote_host"
Returns the remote host (\f(CW\*(C`REMOTE_HOST\*(C'\fR) of the client. It may be
empty, in which case you have to get the \s-1IP\s0 address using \f(CW\*(C`address\*(C'\fR
method and resolve on your own.
.IP "method" 4
.IX Item "method"
Contains the request method (\f(CW\*(C`GET\*(C'\fR, \f(CW\*(C`POST\*(C'\fR, \f(CW\*(C`HEAD\*(C'\fR, etc).
.IP "protocol" 4
.IX Item "protocol"
Returns the protocol (\s-1HTTP/1\s0.0 or \s-1HTTP/1\s0.1) used for the current request.
.IP "request_uri" 4
.IX Item "request_uri"
Returns the raw, undecoded request \s-1URI\s0 path. You probably do \fB\s-1NOT\s0\fR
want to use this to dispatch requests.
.IP "path_info" 4
.IX Item "path_info"
Returns \fB\s-1PATH_INFO\s0\fR in the environment. Use this to get the local
path for the requests.
.IP "path" 4
.IX Item "path"
Similar to \f(CW\*(C`path_info\*(C'\fR but returns \f(CW\*(C`/\*(C'\fR in case it is empty. In other
words, it returns the virtual path of the request \s-1URI\s0 after \f(CW\*(C`$req\->base\*(C'\fR. See \*(L"\s-1DISPATCHING\s0\*(R" for details.
.IP "script_name" 4
.IX Item "script_name"
Returns \fB\s-1SCRIPT_NAME\s0\fR in the environment. This is the absolute path
where your application is hosted.
.IP "scheme" 4
.IX Item "scheme"
Returns the scheme (\f(CW\*(C`http\*(C'\fR or \f(CW\*(C`https\*(C'\fR) of the request.
.IP "secure" 4
.IX Item "secure"
Returns true or false, indicating whether the connection is secure (https).
.IP "body, input" 4
.IX Item "body, input"
Returns \f(CW\*(C`psgi.input\*(C'\fR handle.
.IP "session" 4
.IX Item "session"
Returns (optional) \f(CW\*(C`psgix.session\*(C'\fR hash. When it exists, you can
retrieve and store per-session data from and to this hash.
.IP "session_options" 4
.IX Item "session_options"
Returns (optional) \f(CW\*(C`psgix.session.options\*(C'\fR hash.
.IP "logger" 4
.IX Item "logger"
Returns (optional) \f(CW\*(C`psgix.logger\*(C'\fR code reference. When it exists,
your application is supposed to send the log message to this logger,
using:
.Sp
.Vb 1
\&  $req\->logger\->({ level => \*(Aqdebug\*(Aq, message => "This is a debug message" });
.Ve
.IP "cookies" 4
.IX Item "cookies"
Returns a reference to a hash containing the cookies. Values are
strings that are sent by clients and are \s-1URI\s0 decoded.
.Sp
If there are multiple cookies with the same name in the request, this
method will ignore the duplicates and return only the first value. If
that causes issues for you, you may have to use modules like
CGI::Simple::Cookie to parse \f(CW\*(C`$request\-\*(C'\fRheader('Cookies')> by
yourself.
.IP "query_parameters" 4
.IX Item "query_parameters"
Returns a reference to a hash containing query string (\s-1GET\s0)
parameters. This hash reference is Hash::MultiValue object.
.IP "body_parameters" 4
.IX Item "body_parameters"
Returns a reference to a hash containing posted parameters in the
request body (\s-1POST\s0). As with \f(CW\*(C`query_parameters\*(C'\fR, the hash
reference is a Hash::MultiValue object.
.IP "parameters" 4
.IX Item "parameters"
Returns a Hash::MultiValue hash reference containing (merged) \s-1GET\s0
and \s-1POST\s0 parameters.
.IP "content, raw_body" 4
.IX Item "content, raw_body"
Returns the request content in an undecoded byte string for \s-1POST\s0 requests.
.IP "uri" 4
.IX Item "uri"
Returns an \s-1URI\s0 object for the current request. The \s-1URI\s0 is constructed
using various environment values such as \f(CW\*(C`SCRIPT_NAME\*(C'\fR, \f(CW\*(C`PATH_INFO\*(C'\fR,
\&\f(CW\*(C`QUERY_STRING\*(C'\fR, \f(CW\*(C`HTTP_HOST\*(C'\fR, \f(CW\*(C`SERVER_NAME\*(C'\fR and \f(CW\*(C`SERVER_PORT\*(C'\fR.
.Sp
Every time this method is called it returns a new, cloned \s-1URI\s0 object.
.IP "base" 4
.IX Item "base"
Returns an \s-1URI\s0 object for the base path of current request. This is
like \f(CW\*(C`uri\*(C'\fR but only contains up to \f(CW\*(C`SCRIPT_NAME\*(C'\fR where your
application is hosted at.
.Sp
Every time this method is called it returns a new, cloned \s-1URI\s0 object.
.IP "user" 4
.IX Item "user"
Returns \f(CW\*(C`REMOTE_USER\*(C'\fR if it's set.
.IP "headers" 4
.IX Item "headers"
Returns an HTTP::Headers object containing the headers for the current request.
.IP "uploads" 4
.IX Item "uploads"
Returns a reference to a hash containing uploads. The hash reference
is a Hash::MultiValue object and values are Plack::Request::Upload
objects.
.IP "content_encoding" 4
.IX Item "content_encoding"
Shortcut to \f(CW$req\fR\->headers\->content_encoding.
.IP "content_length" 4
.IX Item "content_length"
Shortcut to \f(CW$req\fR\->headers\->content_length.
.IP "content_type" 4
.IX Item "content_type"
Shortcut to \f(CW$req\fR\->headers\->content_type.
.IP "header" 4
.IX Item "header"
Shortcut to \f(CW$req\fR\->headers\->header.
.IP "referer" 4
.IX Item "referer"
Shortcut to \f(CW$req\fR\->headers\->referer.
.IP "user_agent" 4
.IX Item "user_agent"
Shortcut to \f(CW$req\fR\->headers\->user_agent.
.IP "param" 4
.IX Item "param"
Returns \s-1GET\s0 and \s-1POST\s0 parameters with a \s-1CGI\s0.pm\-compatible param
method. This is an alternative method for accessing parameters in
\&\f(CW$req\fR\->parameters. Unlike \s-1CGI\s0.pm, it does \fInot\fR allow
setting or modifying query parameters.
.Sp
.Vb 3
\&    $value  = $req\->param( \*(Aqfoo\*(Aq );
\&    @values = $req\->param( \*(Aqfoo\*(Aq );
\&    @params = $req\->param;
.Ve
.IP "upload" 4
.IX Item "upload"
A convenient method to access \f(CW$req\fR\->uploads.
.Sp
.Vb 3
\&    $upload  = $req\->upload(\*(Aqfield\*(Aq);
\&    @uploads = $req\->upload(\*(Aqfield\*(Aq);
\&    @fields  = $req\->upload;
\&
\&    for my $upload ( $req\->upload(\*(Aqfield\*(Aq) ) {
\&        print $upload\->filename;
\&    }
.Ve
.IP "new_response" 4
.IX Item "new_response"
.Vb 1
\&  my $res = $req\->new_response;
.Ve
.Sp
Creates a new Plack::Response object. Handy to remove dependency on
Plack::Response in your code for easy subclassing and duck typing
in web application frameworks, as well as overriding Response
generation in middlewares.
.SS "Hash::MultiValue parameters"
.IX Subsection "Hash::MultiValue parameters"
Parameters that can take one or multiple values (i.e. \f(CW\*(C`parameters\*(C'\fR,
\&\f(CW\*(C`query_parameters\*(C'\fR, \f(CW\*(C`body_parameters\*(C'\fR and \f(CW\*(C`uploads\*(C'\fR) store the
hash reference as a Hash::MultiValue object. This means you can use
the hash reference as a plain hash where values are \fBalways\fR scalars
(\fB\s-1NOT\s0\fR array references), so you don't need to code ugly and unsafe
\&\f(CW\*(C`ref ... eq \*(AqARRAY\*(Aq\*(C'\fR anymore.
.PP
And if you explicitly want to get multiple values of the same key, you
can call the \f(CW\*(C`get_all\*(C'\fR method on it, such as:
.PP
.Vb 1
\&  my @foo = $req\->query_parameters\->get_all(\*(Aqfoo\*(Aq);
.Ve
.PP
You can also call \f(CW\*(C`get_one\*(C'\fR to always get one parameter independent
of the context (unlike \f(CW\*(C`param\*(C'\fR), and even call \f(CW\*(C`mixed\*(C'\fR (with
Hash::MultiValue 0.05 or later) to get the \fItraditional\fR hash
reference,
.PP
.Vb 1
\&  my $params = $req\->parameters\->mixed;
.Ve
.PP
where values are either a scalar or an array reference depending on
input, so it might be useful if you already have the code to deal with
that ugliness.
.SS "\s-1PARSING\s0 \s-1POST\s0 \s-1BODY\s0 and \s-1MULTIPLE\s0 \s-1OBJECTS\s0"
.IX Subsection "PARSING POST BODY and MULTIPLE OBJECTS"
The methods to parse request body (\f(CW\*(C`content\*(C'\fR, \f(CW\*(C`body_parameters\*(C'\fR and
\&\f(CW\*(C`uploads\*(C'\fR) are carefully coded to save the parsed body in the
environment hash as well as in the temporary buffer, so you can call
them multiple times and create Plack::Request objects multiple times
in a request and they should work safely, and won't parse request body
more than twice for the efficiency.
.SH "DISPATCHING"
.IX Header "DISPATCHING"
If your application or framework wants to dispatch (or route) actions
based on request paths, be sure to use \f(CW\*(C`$req\->path_info\*(C'\fR not \f(CW\*(C`$req\->uri\->path\*(C'\fR.
.PP
This is because \f(CW\*(C`path_info\*(C'\fR gives you the virtual path of the request,
regardless of how your application is mounted. If your application is
hosted with mod_perl or \s-1CGI\s0 scripts, or even multiplexed with tools
like Plack::App::URLMap, request's \f(CW\*(C`path_info\*(C'\fR always gives you
the action path.
.PP
Note that \f(CW\*(C`path_info\*(C'\fR might give you an empty string, in which case
you should assume that the path is \f(CW\*(C`/\*(C'\fR.
.PP
You will also want to use \f(CW\*(C`$req\->base\*(C'\fR as a base prefix when
building URLs in your templates or in redirections. It's a good idea
for you to subclass Plack::Request and define methods such as:
.PP
.Vb 7
\&  sub uri_for {
\&      my($self, $path, $args) = @_;
\&      my $uri = $self\->base;
\&      $uri\->path($uri\->path . $path);
\&      $uri\->query_form(@$args) if $args;
\&      $uri;
\&  }
.Ve
.PP
So you can say:
.PP
.Vb 1
\&  my $link = $req\->uri_for(\*(Aq/logout\*(Aq, [ signoff => 1 ]);
.Ve
.PP
and if \f(CW\*(C`$req\->base\*(C'\fR is \f(CW\*(C`/app\*(C'\fR you'll get the full \s-1URI\s0 for
\&\f(CW\*(C`/app/logout?signoff=1\*(C'\fR.
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
In version 0.99, many utility methods are removed or deprecated, and
most methods are made read-only. These methods were deleted in version
1.0001.
.PP
All parameter-related methods such as \f(CW\*(C`parameters\*(C'\fR,
\&\f(CW\*(C`body_parameters\*(C'\fR, \f(CW\*(C`query_parameters\*(C'\fR and \f(CW\*(C`uploads\*(C'\fR now contains
Hash::MultiValue objects, rather than \fIscalar or an array
reference depending on the user input\fR which is insecure. See
Hash::MultiValue for more about this change.
.PP
\&\f(CW\*(C`$req\->path\*(C'\fR method had a bug, where the code and the document
was mismatching. The document was suggesting it returns the sub
request path after \f(CW\*(C`$req\->base\*(C'\fR but the code was always returning
the absolute \s-1URI\s0 path. The code is now updated to be an alias of \f(CW\*(C`$req\->path_info\*(C'\fR but returns \f(CW\*(C`/\*(C'\fR in case it's empty. If you need
the older behavior, just call \f(CW\*(C`$req\->uri\->path\*(C'\fR instead.
.PP
Cookie handling is simplified, and doesn't use CGI::Simple::Cookie
anymore, which means you \fB\s-1CAN\s0 \s-1NOT\s0\fR set array reference or hash
reference as a cookie value and expect it be serialized. You're always
required to set string value, and encoding or decoding them is totally
up to your application or framework. Also, \f(CW\*(C`cookies\*(C'\fR hash reference
now returns \fIstrings\fR for the cookies rather than CGI::Simple::Cookie
objects, which means you no longer have to write a wacky code such as:
.PP
.Vb 1
\&  $v = $req\->cookie\->{foo} ? $req\->cookie\->{foo}\->value : undef;
.Ve
.PP
and instead, simply do:
.PP
.Vb 1
\&  $v = $req\->cookie\->{foo};
.Ve
.SH "AUTHORS"
.IX Header "AUTHORS"
Tatsuhiko Miyagawa
.PP
Kazuhiro Osawa
.PP
Tokuhiro Matsuno
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Plack::Response HTTP::Request, Catalyst::Request
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.