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

NAME

6       Catalyst::Request - provides information about the current client
7       request
8

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

SETUP METHODS

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

AUTHORS

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.32.0                      2020-07-28              Catalyst::Request(3)
Impressum