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->parameters->{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 If you're looking for an easy-to-use API to convert existing CGI
43 applications to run on PSGI, consider using CGI::PSGI or
44 CGI::Emulate::PSGI as well. CGI::Emulate::PSGI documentation has a good
45 summary of using them to convert existing CGI scripts to adapt to PSGI.
46
48 Some of the methods defined in the earlier versions are deprecated in
49 version 0.99. Take a look at "INCOMPATIBILITIES".
50 Unless otherwise noted, all methods and attributes are read-only, and
52 passing values to the method like an accessor doesn't work like you
53 expect it to.
54 new
56 Plack::Request->new( $env );
57 Creates a new request object.
59
61 env Returns the shared PSGI environment hash reference. This is a
62 reference, so writing to this environment passes through during the
63 whole PSGI request/response cycle.
64 address
66 Returns the IP address of the client ("REMOTE_ADDR").
67 remote_host
69 Returns the remote host ("REMOTE_HOST") of the client. It may be
70 empty, in which case you have to get the IP address using "address"
71 method and resolve on your own.
72 method
74 Contains the request method ("GET", "POST", "HEAD", etc).
75 protocol
77 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
78 request.
79 request_uri
81 Returns the raw, undecoded request URI path. You probably do NOT
82 want to use this to dispatch requests.
83 path_info
85 Returns PATH_INFO in the environment. Use this to get the local
86 path for the requests.
87 path
89 Similar to "path_info" but returns "/" in case it is empty. In
90 other words, it returns the virtual path of the request URI after
91 "$req->base". See "DISPATCHING" for details.
92 query_string
94 Returns QUERY_STRING in the environment. This is the undecoded
95 query string in the request URI.
96 script_name
98 Returns SCRIPT_NAME in the environment. This is the absolute path
99 where your application is hosted.
100 scheme
102 Returns the scheme ("http" or "https") of the request.
103 secure
105 Returns true or false, indicating whether the connection is secure
106 (https).
107 body, input
109 Returns "psgi.input" handle.
110 session
112 Returns (optional) "psgix.session" hash. When it exists, you can
113 retrieve and store per-session data from and to this hash.
114 session_options
116 Returns (optional) "psgix.session.options" hash.
117 logger
119 Returns (optional) "psgix.logger" code reference. When it exists,
120 your application is supposed to send the log message to this
121 logger, using:
122 $req->logger->({ level => 'debug', message => "This is a debug message" });
124 cookies
126 Returns a reference to a hash containing the cookies. Values are
127 strings that are sent by clients and are URI decoded.
128 If there are multiple cookies with the same name in the request,
130 this method will ignore the duplicates and return only the first
131 value. If that causes issues for you, you may have to use modules
132 like CGI::Simple::Cookie to parse "$request->header('Cookie')" by
133 yourself.
134 query_parameters
136 Returns a reference to a hash containing query string (GET)
137 parameters. This hash reference is Hash::MultiValue object.
138 body_parameters
140 Returns a reference to a hash containing posted parameters in the
141 request body (POST). As with "query_parameters", the hash reference
142 is a Hash::MultiValue object.
143 parameters
145 Returns a Hash::MultiValue hash reference containing (merged) GET
146 and POST parameters.
147 content, raw_body
149 Returns the request content in an undecoded byte string for POST
150 requests.
151 uri Returns an URI object for the current request. The URI is
153 constructed using various environment values such as "SCRIPT_NAME",
154 "PATH_INFO", "QUERY_STRING", "HTTP_HOST", "SERVER_NAME" and
155 "SERVER_PORT".
156 Every time this method is called it returns a new, cloned URI
158 object.
159 base
161 Returns an URI object for the base path of current request. This is
162 like "uri" but only contains up to "SCRIPT_NAME" where your
163 application is hosted at.
164 Every time this method is called it returns a new, cloned URI
166 object.
167 user
169 Returns "REMOTE_USER" if it's set.
170 headers
172 Returns an HTTP::Headers::Fast object containing the headers for
173 the current request.
174 uploads
176 Returns a reference to a hash containing uploads. The hash
177 reference is a Hash::MultiValue object and values are
178 Plack::Request::Upload objects.
179 content_encoding
181 Shortcut to $req->headers->content_encoding.
182 content_length
184 Returns the raw value of the Content-Length header.
185 Before version 0.9925, this method was a shortcut for
187 "$req->headers->content_length".
188 content_type
190 Returns the raw value of the Content-Type header.
191 If you want just the MIME type, without any attributes like
193 charset, use "$req->headers->content_type". See also
194 "content_type" in HTTP::Headers.
195 Before version 0.9925, this method was a shortcut for
197 "$req->headers->content_type".
198 header
200 Shortcut to $req->headers->header.
201 referer
203 Shortcut to $req->headers->referer.
204 user_agent
206 Shortcut to $req->headers->user_agent.
207 param
209 Returns GET and POST parameters with a CGI.pm-compatible param
210 method. This is an alternative method for accessing parameters in
211 $req->parameters just in case you want the compatibility with
212 CGI.pm objects.
213 You are not recommended to use this method since it is easy to
215 misuse in a list context such as inside a hash constructor or
216 method arguments. Use "parameters" and Hash::MultiValue instead.
217 Unlike CGI.pm, it does not allow setting or modifying query
219 parameters.
220 $value = $req->param( 'foo' );
222 @values = $req->param( 'foo' );
223 @params = $req->param;
224 upload
226 A convenient method to access $req->uploads.
227 $upload = $req->upload('field');
229 @uploads = $req->upload('field');
230 @fields = $req->upload;
231 for my $upload ( $req->upload('field') ) {
233 print $upload->filename;
234 }
235 new_response
237 my $res = $req->new_response;
238 Creates a new Plack::Response object. Handy to remove dependency on
240 Plack::Response in your code for easy subclassing and duck typing
241 in web application frameworks, as well as overriding Response
242 generation in middlewares.
243 Hash::MultiValue parameters
245 Parameters that can take one or multiple values (i.e. "parameters",
246 "query_parameters", "body_parameters" and "uploads") store the hash
247 reference as a Hash::MultiValue object. This means you can use the hash
248 reference as a plain hash where values are always scalars (NOT array
249 references), so you don't need to code ugly and unsafe "ref ... eq
250 'ARRAY'" anymore.
251 And if you explicitly want to get multiple values of the same key, you
253 can call the "get_all" method on it, such as:
254 my @foo = $req->query_parameters->get_all('foo');
256 You can also call "get_one" to always get one parameter independent of
258 the context (unlike "param"), and even call "mixed" (with
259 Hash::MultiValue 0.05 or later) to get the traditional hash reference,
260 my $params = $req->parameters->mixed;
262 where values are either a scalar or an array reference depending on
264 input, so it might be useful if you already have the code to deal with
265 that ugliness.
266 PARSING POST BODY and MULTIPLE OBJECTS
268 The methods to parse request body ("content", "body_parameters" and
269 "uploads") are carefully coded to save the parsed body in the
270 environment hash as well as in the temporary buffer, so you can call
271 them multiple times and create Plack::Request objects multiple times in
272 a request and they should work safely, and won't parse request body
273 more than twice for the efficiency.
274
276 If your application or framework wants to dispatch (or route) actions
277 based on request paths, be sure to use "$req->path_info" not
278 "$req->uri->path".
279 This is because "path_info" gives you the virtual path of the request,
281 regardless of how your application is mounted. If your application is
282 hosted with mod_perl or CGI scripts, or even multiplexed with tools
283 like Plack::App::URLMap, request's "path_info" always gives you the
284 action path.
285 Note that "path_info" might give you an empty string, in which case you
287 should assume that the path is "/".
288 You will also want to use "$req->base" as a base prefix when building
290 URLs in your templates or in redirections. It's a good idea for you to
291 subclass Plack::Request and define methods such as:
292 sub uri_for {
294 my($self, $path, $args) = @_;
295 my $uri = $self->base;
296 $uri->path($uri->path . $path);
297 $uri->query_form(@$args) if $args;
298 $uri;
299 }
300 So you can say:
302 my $link = $req->uri_for('/logout', [ signoff => 1 ]);
304 and if "$req->base" is "/app" you'll get the full URI for
306 "/app/logout?signoff=1".
307
309 In version 0.99, many utility methods are removed or deprecated, and
310 most methods are made read-only. These methods were deleted in version
311 1.0001.
312 All parameter-related methods such as "parameters", "body_parameters",
314 "query_parameters" and "uploads" now contains Hash::MultiValue objects,
315 rather than scalar or an array reference depending on the user input
316 which is insecure. See Hash::MultiValue for more about this change.
317 "$req->path" method had a bug, where the code and the document was
319 mismatching. The document was suggesting it returns the sub request
320 path after "$req->base" but the code was always returning the absolute
321 URI path. The code is now updated to be an alias of "$req->path_info"
322 but returns "/" in case it's empty. If you need the older behavior,
323 just call "$req->uri->path" instead.
324 Cookie handling is simplified, and doesn't use CGI::Simple::Cookie
326 anymore, which means you CAN NOT set array reference or hash reference
327 as a cookie value and expect it be serialized. You're always required
328 to set string value, and encoding or decoding them is totally up to
329 your application or framework. Also, "cookies" hash reference now
330 returns strings for the cookies rather than CGI::Simple::Cookie
331 objects, which means you no longer have to write a wacky code such as:
332 $v = $req->cookies->{foo} ? $req->cookies->{foo}->value : undef;
334 and instead, simply do:
336 $v = $req->cookies->{foo};
338
340 Tatsuhiko Miyagawa
341 Kazuhiro Osawa
343 Tokuhiro Matsuno
345
347 Plack::Response HTTP::Request, Catalyst::Request
348
350 This library is free software; you can redistribute it and/or modify it
351 under the same terms as Perl itself.
352perl v5.32.0 2020-12-02 Plack::Request(3)