1Plack::Request(3) User Contributed Perl Documentation Plack::Request(3)
2
6 Plack::Request - Portable HTTP request object from PSGI env hash
7
9 use Plack::Request;
10 my $app_or_middleware = sub {
12 my $env = shift; # PSGI env
13 my $req = Plack::Request->new($env);
15 my $path_info = $req->path_info;
17 my $query = $req->param('query');
18 my $res = $req->new_response(200); # new Plack::Response
20 $res->finalize;
21 };
22
24 Plack::Request provides a consistent API for request objects across web
25 server environments.
26
28 Note that this module is intended to be used by Plack middleware
29 developers and web application framework developers rather than
30 application developers (end users).
31 Writing your web application directly using Plack::Request is certainly
33 possible but not recommended: it's like doing so with mod_perl's
34 Apache::Request: yet too low level.
35 If you're writing a web application, not a framework, then you're
37 encouraged to use one of the web application frameworks that support
38 PSGI (<http://plackperl.org/#frameworks>), or see modules like
39 HTTP::Engine to provide higher level Request and Response API on top of
40 PSGI.
41
43 Some of the methods defined in the earlier versions are deprecated in
44 version 0.99. Take a look at "INCOMPATIBILITIES".
45 Unless otherwise noted, all methods and attributes are read-only, and
47 passing values to the method like an accessor doesn't work like you
48 expect it to.
49 new
51 Plack::Request->new( $env );
52 Creates a new request object.
54
56 env Returns the shared PSGI environment hash reference. This is a
57 reference, so writing to this environment passes through during the
58 whole PSGI request/response cycle.
59 address
61 Returns the IP address of the client ("REMOTE_ADDR").
62 remote_host
64 Returns the remote host ("REMOTE_HOST") of the client. It may be
65 empty, in which case you have to get the IP address using "address"
66 method and resolve on your own.
67 method
69 Contains the request method ("GET", "POST", "HEAD", etc).
70 protocol
72 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
73 request.
74 request_uri
76 Returns the raw, undecoded request URI path. You probably do NOT
77 want to use this to dispatch requests.
78 path_info
80 Returns PATH_INFO in the environment. Use this to get the local
81 path for the requests.
82 path
84 Similar to "path_info" but returns "/" in case it is empty. In
85 other words, it returns the virtual path of the request URI after
86 "$req->base". See "DISPATCHING" for details.
87 script_name
89 Returns SCRIPT_NAME in the environment. This is the absolute path
90 where your application is hosted.
91 scheme
93 Returns the scheme ("http" or "https") of the request.
94 secure
96 Returns true or false, indicating whether the connection is secure
97 (https).
98 body, input
100 Returns "psgi.input" handle.
101 session
103 Returns (optional) "psgix.session" hash. When it exists, you can
104 retrieve and store per-session data from and to this hash.
105 session_options
107 Returns (optional) "psgix.session.options" hash.
108 logger
110 Returns (optional) "psgix.logger" code reference. When it exists,
111 your application is supposed to send the log message to this
112 logger, using:
113 $req->logger->({ level => 'debug', message => "This is a debug message" });
115 cookies
117 Returns a reference to a hash containing the cookies. Values are
118 strings that are sent by clients and are URI decoded.
119 query_parameters
121 Returns a reference to a hash containing query string (GET)
122 parameters. This hash reference is Hash::MultiValue object.
123 body_parameters
125 Returns a reference to a hash containing posted parameters in the
126 request body (POST). As with "query_parameters", the hash reference
127 is a Hash::MultiValue object.
128 parameters
130 Returns a Hash::MultiValue hash reference containing (merged) GET
131 and POST parameters.
132 content, raw_body
134 Returns the request content in an undecoded byte string for POST
135 requests.
136 uri Returns an URI object for the current request. The URI is
138 constructed using various environment values such as "SCRIPT_NAME",
139 "PATH_INFO", "QUERY_STRING", "HTTP_HOST", "SERVER_NAME" and
140 "SERVER_PORT".
141 Every time this method is called it returns a new, cloned URI
143 object.
144 base
146 Returns an URI object for the base path of current request. This is
147 like "uri" but only contains up to "SCRIPT_NAME" where your
148 application is hosted at.
149 Every time this method is called it returns a new, cloned URI
151 object.
152 user
154 Returns "REMOTE_USER" if it's set.
155 headers
157 Returns an HTTP::Headers object containing the headers for the
158 current request.
159 uploads
161 Returns a reference to a hash containing uploads. The hash
162 reference is a Hash::MultiValue object and values are
163 Plack::Request::Upload objects.
164 content_encoding
166 Shortcut to $req->headers->content_encoding.
167 content_length
169 Shortcut to $req->headers->content_length.
170 content_type
172 Shortcut to $req->headers->content_type.
173 header
175 Shortcut to $req->headers->header.
176 referer
178 Shortcut to $req->headers->referer.
179 user_agent
181 Shortcut to $req->headers->user_agent.
182 param
184 Returns GET and POST parameters with a CGI.pm-compatible param
185 method. This is an alternative method for accessing parameters in
186 $req->parameters. Unlike CGI.pm, it does not allow setting or
187 modifying query parameters.
188 $value = $req->param( 'foo' );
190 @values = $req->param( 'foo' );
191 @params = $req->param;
192 upload
194 A convenient method to access $req->uploads.
195 $upload = $req->upload('field');
197 @uploads = $req->upload('field');
198 @fields = $req->upload;
199 for my $upload ( $req->upload('field') ) {
201 print $upload->filename;
202 }
203 new_response
205 my $res = $req->new_response;
206 Creates a new Plack::Response object. Handy to remove dependency on
208 Plack::Response in your code for easy subclassing and duck typing
209 in web application frameworks, as well as overriding Response
210 generation in middlewares.
211 Hash::MultiValue parameters
213 Parameters that can take one or multiple values (i.e. "parameters",
214 "query_parameters", "body_parameters" and "uploads") store the hash
215 reference as a Hash::MultiValue object. This means you can use the hash
216 reference as a plain hash where values are always scalars (NOT array
217 references), so you don't need to code ugly and unsafe "ref ... eq
218 'ARRAY'" anymore.
219 And if you explicitly want to get multiple values of the same key, you
221 can call the "get_all" method on it, such as:
222 my @foo = $req->query_parameters->get_all('foo');
224 You can also call "get_one" to always get one parameter independent of
226 the context (unlike "param"), and even call "mixed" (with
227 Hash::MultiValue 0.05 or later) to get the traditional hash reference,
228 my $params = $req->parameters->mixed;
230 where values are either a scalar or an array reference depending on
232 input, so it might be useful if you already have the code to deal with
233 that ugliness.
234 PARSING POST BODY and MULTIPLE OBJECTS
236 The methods to parse request body ("content", "body_parameters" and
237 "uploads") are carefully coded to save the parsed body in the
238 environment hash as well as in the temporary buffer, so you can call
239 them multiple times and create Plack::Request objects multiple times in
240 a request and they should work safely, and won't parse request body
241 more than twice for the efficiency.
242
244 If your application or framework wants to dispatch (or route) actions
245 based on request paths, be sure to use "$req->path_info" not
246 "$req->uri->path".
247 This is because "path_info" gives you the virtual path of the request,
249 regardless of how your application is mounted. If your application is
250 hosted with mod_perl or CGI scripts, or even multiplexed with tools
251 like Plack::App::URLMap, request's "path_info" always gives you the
252 action path.
253 Note that "path_info" might give you an empty string, in which case you
255 should assume that the path is "/".
256 You will also want to use "$req->base" as a base prefix when building
258 URLs in your templates or in redirections. It's a good idea for you to
259 subclass Plack::Request and define methods such as:
260 sub uri_for {
262 my($self, $path, $args) = @_;
263 my $uri = $self->base;
264 $uri->path($uri->path . $path);
265 $uri->query_form(@$args) if $args;
266 $uri;
267 }
268 So you can say:
270 my $link = $req->uri_for('/logout', [ signoff => 1 ]);
272 and if "$req->base" is "/app" you'll get the full URI for
274 "/app/logout?signoff=1".
275
277 In version 0.99, many utility methods are removed or deprecated, and
278 most methods are made read-only.
279 The following methods are deprecated: "hostname", "url_scheme",
281 "params", "query_params", "body_params", "cookie" and "raw_uri". They
282 will be removed in the next major release.
283 All parameter-related methods such as "parameters", "body_parameters",
285 "query_parameters" and "uploads" now contains Hash::MultiValue objects,
286 rather than scalar or an array reference depending on the user input
287 which is insecure. See Hash::MultiValue for more about this change.
288 "$req->path" method had a bug, where the code and the document was
290 mismatching. The document was suggesting it returns the sub request
291 path after "$req->base" but the code was always returning the absolute
292 URI path. The code is now updated to be an alias of "$req->path_info"
293 but returns "/" in case it's empty. If you need the older behavior,
294 just call "$req->uri->path" instead.
295 Cookie handling is simplified, and doesn't use CGI::Simple::Cookie
297 anymore, which means you CAN NOT set array reference or hash reference
298 as a cookie value and expect it be serialized. You're always required
299 to set string value, and encoding or decoding them is totally up to
300 your application or framework. Also, "cookies" hash reference now
301 returns strings for the cookies rather than CGI::Simple::Cookie
302 objects, which means you no longer have to write a wacky code such as:
303 $v = $req->cookie->{foo} ? $req->cookie->{foo}->value : undef;
305 and instead, simply do:
307 $v = $req->cookie->{foo};
309
311 Tatsuhiko Miyagawa
312 Kazuhiro Osawa
314 Tokuhiro Matsuno
316
318 Plack::Response HTTP::Request, Catalyst::Request
319
321 This library is free software; you can redistribute it and/or modify it
322 under the same terms as Perl itself.
323perl v5.12.3 2011-07-19 Plack::Request(3)