1Catalyst::Request(3) User Contributed Perl Documentation Catalyst::Request(3)
2
3
4
6 Catalyst::Request - provides information about the current client
7 request
8
10 $req = $c->request;
11 $req->address eq "127.0.0.1";
12 $req->arguments;
13 $req->args;
14 $req->base;
15 $req->body;
16 $req->body_data;
17 $req->body_parameters;
18 $req->content_encoding;
19 $req->content_length;
20 $req->content_type;
21 $req->cookie;
22 $req->cookies;
23 $req->header;
24 $req->headers;
25 $req->hostname;
26 $req->input;
27 $req->query_keywords;
28 $req->match;
29 $req->method;
30 $req->param;
31 $req->parameters;
32 $req->params;
33 $req->path;
34 $req->protocol;
35 $req->query_parameters;
36 $req->read;
37 $req->referer;
38 $req->secure;
39 $req->captures;
40 $req->upload;
41 $req->uploads;
42 $req->uri;
43 $req->user;
44 $req->user_agent;
45 $req->env;
46
47 See also Catalyst, Catalyst::Request::Upload.
48
50 This is the Catalyst Request class, which provides an interface to data
51 for the current client request. The request object is prepared by
52 Catalyst::Engine, thus hiding the details of the particular engine
53 implementation.
54
56 $req->address
57 Returns the IP address of the client.
58
59 $req->arguments
60 Returns a reference to an array containing the arguments.
61
62 print $c->request->arguments->[0];
63
64 For example, if your action was
65
66 package MyApp::Controller::Foo;
67
68 sub moose : Local {
69 ...
70 }
71
72 and the URI for the request was "http://.../foo/moose/bah", the string
73 "bah" would be the first and only argument.
74
75 Arguments get automatically URI-unescaped for you.
76
77 $req->args
78 Shortcut for "arguments".
79
80 $req->base
81 Contains the URI base. This will always have a trailing slash. Note
82 that the URI scheme (e.g., http vs. https) must be determined through
83 heuristics; depending on your server configuration, it may be
84 incorrect. See $req->secure for more info.
85
86 If your application was queried with the URI
87 "http://localhost:3000/some/path" then "base" is
88 "http://localhost:3000/".
89
90 $req->body
91 Returns the message body of the request, as returned by HTTP::Body: a
92 string, unless Content-Type is "application/x-www-form-urlencoded",
93 "text/xml", or "multipart/form-data", in which case a File::Temp object
94 is returned.
95
96 $req->body_data
97 Returns a Perl representation of POST/PUT body data that is not classic
98 HTML form data, such as JSON, XML, etc. By default, Catalyst will
99 parse incoming data of the type 'application/json' and return access to
100 that data via this method. You may define addition data_handlers via a
101 global configuration setting. See "Catalyst\DATA HANDLERS" for more
102 information.
103
104 If the POST is malformed in some way (such as undefined or not content
105 that matches the content-type) we raise a Catalyst::Exception with the
106 error text as the message.
107
108 If the POSTed content type does not match an available data handler,
109 this will also raise an exception.
110
111 $req->body_parameters
112 Returns a reference to a hash containing body (POST) parameters. Values
113 can be either a scalar or an arrayref containing scalars.
114
115 print $c->request->body_parameters->{field};
116 print $c->request->body_parameters->{field}->[0];
117
118 These are the parameters from the POST part of the request, if any.
119
120 NOTE If your POST is multipart, but contains non file upload parts
121 (such as an line part with an alternative encoding or content type) we
122 do our best to try and figure out how the value should be presented.
123 If there's a specified character set we will use that to decode rather
124 than the default encoding set by the application. However if there are
125 complex headers and we cannot determine the correct way to extra a
126 meaningful value from the upload, in this case any part like this will
127 be represented as an instance of Catalyst::Request::PartData.
128
129 Patches and review of this part of the code welcomed.
130
131 $req->body_params
132 Shortcut for body_parameters.
133
134 $req->content_encoding
135 Shortcut for $req->headers->content_encoding.
136
137 $req->content_length
138 Shortcut for $req->headers->content_length.
139
140 $req->content_type
141 Shortcut for $req->headers->content_type.
142
143 $req->cookie
144 A convenient method to access $req->cookies.
145
146 $cookie = $c->request->cookie('name');
147 @cookies = $c->request->cookie;
148
149 $req->cookies
150 Returns a reference to a hash containing the cookies.
151
152 print $c->request->cookies->{mycookie}->value;
153
154 The cookies in the hash are indexed by name, and the values are
155 CGI::Simple::Cookie objects.
156
157 $req->header
158 Shortcut for $req->headers->header.
159
160 $req->headers
161 Returns an HTTP::Headers object containing the headers for the current
162 request.
163
164 print $c->request->headers->header('X-Catalyst');
165
166 $req->hostname
167 Returns the hostname of the client. Use "$req->uri->host" to get the
168 hostname of the server.
169
170 $req->input
171 Alias for $req->body.
172
173 $req->query_keywords
174 Contains the keywords portion of a query string, when no '=' signs are
175 present.
176
177 http://localhost/path?some+keywords
178
179 $c->request->query_keywords will contain 'some keywords'
180
181 $req->match
182 This contains the matching part of a Regex action. Otherwise it returns
183 the same as 'action', except for default actions, which return an empty
184 string.
185
186 $req->method
187 Contains the request method ("GET", "POST", "HEAD", etc).
188
189 $req->param
190 Returns GET and POST parameters with a CGI.pm-compatible param method.
191 This is an alternative method for accessing parameters in
192 $c->req->parameters.
193
194 $value = $c->request->param( 'foo' );
195 @values = $c->request->param( 'foo' );
196 @params = $c->request->param;
197
198 Like CGI, and unlike earlier versions of Catalyst, passing multiple
199 arguments to this method, like this:
200
201 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
202
203 will set the parameter "foo" to the multiple values "bar", "gorch" and
204 "quxx". Previously this would have added "bar" as another value to
205 "foo" (creating it if it didn't exist before), and "quxx" as another
206 value for "gorch".
207
208 NOTE this is considered a legacy interface and care should be taken
209 when using it. "scalar $c->req->param( 'foo' )" will return only the
210 first "foo" param even if multiple are present; "$c->req->param( 'foo'
211 )" will return a list of as many are present, which can have unexpected
212 consequences when writing code of the form:
213
214 $foo->bar(
215 a => 'b',
216 baz => $c->req->param( 'baz' ),
217 );
218
219 If multiple "baz" parameters are provided this code might corrupt data
220 or cause a hash initialization error. For a more straightforward
221 interface see "$c->req->parameters".
222
223 NOTE Interfaces like this, which are based on CGI and the "param"
224 method are known to cause demonstrated exploits. It is highly
225 recommended that you avoid using this method, and migrate existing code
226 away from it. Here's a whitepaper of the exploit:
227
228 <http://blog.gerv.net/2014/10/new-class-of-vulnerability-in-perl-web-applications/>
229
230 NOTE Further discussion on IRC indicate that the Catalyst core team
231 from 'back then' were well aware of this hack and this is the main
232 reason we added the new approach to getting parameters in the first
233 place.
234
235 Basically this is an exploit that takes advantage of how \param will do
236 one thing in scalar context and another thing in list context. This is
237 combined with how Perl chooses to deal with duplicate keys in a hash
238 definition by overwriting the value of existing keys with a new value
239 if the same key shows up again. Generally you will be vulnerable to
240 this exploit if you are using this method in a direct assignment in a
241 hash, such as with a DBIx::Class create statement. For example, if you
242 have parameters like:
243
244 user?user=123&foo=a&foo=user&foo=456
245
246 You could end up with extra parameters injected into your method calls:
247
248 $c->model('User')->create({
249 user => $c->req->param('user'),
250 foo => $c->req->param('foo'),
251 });
252
253 Which would look like:
254
255 $c->model('User')->create({
256 user => 123,
257 foo => qw(a user 456),
258 });
259
260 (or to be absolutely clear if you are not seeing it):
261
262 $c->model('User')->create({
263 user => 456,
264 foo => 'a',
265 });
266
267 Possible remediations include scrubbing your parameters with a form
268 validator like HTML::FormHandler or being careful to force scalar
269 context using the scalar keyword:
270
271 $c->model('User')->create({
272 user => scalar($c->req->param('user')),
273 foo => scalar($c->req->param('foo')),
274 });
275
276 Upcoming versions of Catalyst will disable this interface by default
277 and require you to positively enable it should you require it for
278 backwards compatibility reasons.
279
280 $req->parameters
281 Returns a reference to a hash containing GET and POST parameters.
282 Values can be either a scalar or an arrayref containing scalars.
283
284 print $c->request->parameters->{field};
285 print $c->request->parameters->{field}->[0];
286
287 This is the combination of "query_parameters" and "body_parameters".
288
289 $req->params
290 Shortcut for $req->parameters.
291
292 $req->path
293 Returns the path, i.e. the part of the URI after $req->base, for the
294 current request.
295
296 http://localhost/path/foo
297
298 $c->request->path will contain 'path/foo'
299
300 $req->path_info
301 Alias for path, added for compatibility with CGI.
302
303 $req->protocol
304 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
305 request.
306
307 $req->query_parameters
308 $req->query_params
309 Returns a reference to a hash containing query string (GET) parameters.
310 Values can be either a scalar or an arrayref containing scalars.
311
312 print $c->request->query_parameters->{field};
313 print $c->request->query_parameters->{field}->[0];
314
315 $req->read( [$maxlength] )
316 Reads a chunk of data from the request body. This method is intended to
317 be used in a while loop, reading $maxlength bytes on every call.
318 $maxlength defaults to the size of the request if not specified.
319
320 $req->read_chunk(\$buff, $max)
321 Reads a chunk.
322
323 You have to set MyApp->config(parse_on_demand => 1) to use this
324 directly.
325
326 $req->referer
327 Shortcut for $req->headers->referer. Returns the referring page.
328
329 $req->secure
330 Returns true or false, indicating whether the connection is secure
331 (https). The reliability of $req->secure may depend on your server
332 configuration; Catalyst relies on PSGI to determine whether or not a
333 request is secure (Catalyst looks at psgi.url_scheme), and different
334 PSGI servers may make this determination in different ways (as by
335 directly passing along information from the server, interpreting any of
336 several HTTP headers, or using heuristics of their own).
337
338 $req->captures
339 Returns a reference to an array containing captured args from chained
340 actions or regex captures.
341
342 my @captures = @{ $c->request->captures };
343
344 $req->upload
345 A convenient method to access $req->uploads.
346
347 $upload = $c->request->upload('field');
348 @uploads = $c->request->upload('field');
349 @fields = $c->request->upload;
350
351 for my $upload ( $c->request->upload('field') ) {
352 print $upload->filename;
353 }
354
355 $req->uploads
356 Returns a reference to a hash containing uploads. Values can be either
357 a Catalyst::Request::Upload object, or an arrayref of
358 Catalyst::Request::Upload objects.
359
360 my $upload = $c->request->uploads->{field};
361 my $upload = $c->request->uploads->{field}->[0];
362
363 $req->uri
364 Returns a URI object for the current request. Stringifies to the URI
365 text.
366
367 $req->mangle_params( { key => 'value' }, $appendmode);
368 Returns a hashref of parameters stemming from the current request's
369 params, plus the ones supplied. Keys for which no current param exists
370 will be added, keys with undefined values will be removed and keys with
371 existing params will be replaced. Note that you can supply a true
372 value as the final argument to change behavior with regards to existing
373 parameters, appending values rather than replacing them.
374
375 A quick example:
376
377 # URI query params foo=1
378 my $hashref = $req->mangle_params({ foo => 2 });
379 # Result is query params of foo=2
380
381 versus append mode:
382
383 # URI query params foo=1
384 my $hashref = $req->mangle_params({ foo => 2 }, 1);
385 # Result is query params of foo=1&foo=2
386
387 This is the code behind "uri_with".
388
389 $req->uri_with( { key => 'value' } );
390 Returns a rewritten URI object for the current request. Key/value pairs
391 passed in will override existing parameters. You can remove an existing
392 parameter by passing in an undef value. Unmodified pairs will be
393 preserved.
394
395 You may also pass an optional second parameter that puts "uri_with"
396 into append mode:
397
398 $req->uri_with( { key => 'value' }, { mode => 'append' } );
399
400 See "mangle_params" for an explanation of this behavior.
401
402 $req->remote_user
403 Returns the value of the "REMOTE_USER" environment variable.
404
405 $req->user_agent
406 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
407 version string.
408
409 $req->io_fh
410 Returns a psgix.io bidirectional socket, if your server supports one.
411 Used for when you want to jailbreak out of PSGI and handle
412 bidirectional client server communication manually, such as when you
413 are using cometd or websockets.
414
416 You should never need to call these yourself in application code,
417 however they are useful if extending Catalyst by applying a request
418 role.
419
420 $self->prepare_headers()
421 Sets up the "$res->headers" accessor.
422
423 $self->prepare_body()
424 Sets up the body using HTTP::Body
425
426 $self->prepare_body_chunk()
427 Add a chunk to the request body.
428
429 $self->prepare_body_parameters()
430 Sets up parameters from body.
431
432 $self->prepare_cookies()
433 Parse cookies from header. Sets up a CGI::Simple::Cookie object.
434
435 $self->prepare_connection()
436 Sets up various fields in the request like the local and remote
437 addresses, request method, hostname requested etc.
438
439 $self->prepare_parameters()
440 Ensures that the body has been parsed, then builds the parameters,
441 which are combined from those in the request and those in the body.
442
443 If parameters have already been set will clear the parameters and build
444 them again.
445
446 $self->env
447 Access to the raw PSGI env.
448
449 meta
450 Provided by Moose
451
453 Catalyst Contributors, see Catalyst.pm
454
456 This library is free software. You can redistribute it and/or modify it
457 under the same terms as Perl itself.
458
459
460
461perl v5.28.1 2019-01-18 Catalyst::Request(3)