1Plack::Request(3)     User Contributed Perl Documentation    Plack::Request(3)
2
3
4

NAME

6       Plack::Request - Portable HTTP request object from PSGI env hash
7

SYNOPSIS

9         use Plack::Request;
10
11         my $app_or_middleware = sub {
12             my $env = shift; # PSGI env
13
14             my $req = Plack::Request->new($env);
15
16             my $path_info = $req->path_info;
17             my $query     = $req->parameters->{query};
18
19             my $res = $req->new_response(200); # new Plack::Response
20             $res->finalize;
21         };
22

DESCRIPTION

24       Plack::Request provides a consistent API for request objects across web
25       server environments.
26

CAVEAT

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
32       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
36       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
42       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

METHODS

48       Some of the methods defined in the earlier versions are deprecated in
49       version 0.99. Take a look at "INCOMPATIBILITIES".
50
51       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
55   new
56           Plack::Request->new( $env );
57
58       Creates a new request object.
59

ATTRIBUTES

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
65       address
66           Returns the IP address of the client ("REMOTE_ADDR").
67
68       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
73       method
74           Contains the request method ("GET", "POST", "HEAD", etc).
75
76       protocol
77           Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
78           request.
79
80       request_uri
81           Returns the raw, undecoded request URI path. You probably do NOT
82           want to use this to dispatch requests.
83
84       path_info
85           Returns PATH_INFO in the environment. Use this to get the local
86           path for the requests.
87
88       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
93       query_string
94           Returns QUERY_STRING in the environment. This is the undecoded
95           query string in the request URI.
96
97       script_name
98           Returns SCRIPT_NAME in the environment. This is the absolute path
99           where your application is hosted.
100
101       scheme
102           Returns the scheme ("http" or "https") of the request.
103
104       secure
105           Returns true or false, indicating whether the connection is secure
106           (https).
107
108       body, input
109           Returns "psgi.input" handle.
110
111       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
115       session_options
116           Returns (optional) "psgix.session.options" hash.
117
118       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
123             $req->logger->({ level => 'debug', message => "This is a debug message" });
124
125       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
129           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
135       query_parameters
136           Returns a reference to a hash containing query string (GET)
137           parameters. This hash reference is Hash::MultiValue object.
138
139       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
144       parameters
145           Returns a Hash::MultiValue hash reference containing (merged) GET
146           and POST parameters.
147
148       content, raw_body
149           Returns the request content in an undecoded byte string for POST
150           requests.
151
152       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
157           Every time this method is called it returns a new, cloned URI
158           object.
159
160       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
165           Every time this method is called it returns a new, cloned URI
166           object.
167
168       user
169           Returns "REMOTE_USER" if it's set.
170
171       headers
172           Returns an HTTP::Headers::Fast object containing the headers for
173           the current request.
174
175       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
180       content_encoding
181           Shortcut to $req->headers->content_encoding.
182
183       content_length
184           Returns the raw value of the Content-Length header.
185
186           Before version 0.9925, this method was a shortcut for
187           "$req->headers->content_length".
188
189       content_type
190           Returns the raw value of the Content-Type header.
191
192           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
196           Before version 0.9925, this method was a shortcut for
197           "$req->headers->content_type".
198
199       header
200           Shortcut to $req->headers->header.
201
202       referer
203           Shortcut to $req->headers->referer.
204
205       user_agent
206           Shortcut to $req->headers->user_agent.
207
208       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
214           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
218           Unlike CGI.pm, it does not allow setting or modifying query
219           parameters.
220
221               $value  = $req->param( 'foo' );
222               @values = $req->param( 'foo' );
223               @params = $req->param;
224
225       upload
226           A convenient method to access $req->uploads.
227
228               $upload  = $req->upload('field');
229               @uploads = $req->upload('field');
230               @fields  = $req->upload;
231
232               for my $upload ( $req->upload('field') ) {
233                   print $upload->filename;
234               }
235
236       new_response
237             my $res = $req->new_response;
238
239           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
244   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
252       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
255         my @foo = $req->query_parameters->get_all('foo');
256
257       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
261         my $params = $req->parameters->mixed;
262
263       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
267   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

DISPATCHING

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
280       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
286       Note that "path_info" might give you an empty string, in which case you
287       should assume that the path is "/".
288
289       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
293         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
301       So you can say:
302
303         my $link = $req->uri_for('/logout', [ signoff => 1 ]);
304
305       and if "$req->base" is "/app" you'll get the full URI for
306       "/app/logout?signoff=1".
307

INCOMPATIBILITIES

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
313       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
318       "$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
325       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
333         $v = $req->cookies->{foo} ? $req->cookies->{foo}->value : undef;
334
335       and instead, simply do:
336
337         $v = $req->cookies->{foo};
338

AUTHORS

340       Tatsuhiko Miyagawa
341
342       Kazuhiro Osawa
343
344       Tokuhiro Matsuno
345

SEE ALSO

347       Plack::Response HTTP::Request, Catalyst::Request
348

LICENSE

350       This library is free software; you can redistribute it and/or modify it
351       under the same terms as Perl itself.
352
353
354
355perl v5.34.0                      2022-01-21                 Plack::Request(3)
Impressum