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 body data that is not classic HTML
98       form data, such as JSON, XML, etc.  By default, Catalyst will parse
99       incoming data of the type 'application/json' for POST, PUT, PATCH or
100       DELETE methods, and return access to that data via this method.
101
102       You may define addition data_handlers via a global configuration
103       setting.  See "Catalyst\DATA HANDLERS" for more information.
104
105       If the body is malformed in some way (such as undefined or not content
106       that matches the content-type) we raise a Catalyst::Exception with the
107       error text as the message.
108
109       If the body content type does not match an available data handler, this
110       will also raise an exception.
111
112   $req->body_parameters
113       Returns a reference to a hash containing body (POST) parameters. Values
114       can be either a scalar or an arrayref containing scalars.
115
116           print $c->request->body_parameters->{field};
117           print $c->request->body_parameters->{field}->[0];
118
119       These are the parameters from the POST part of the request, if any.
120
121       NOTE If your POST is multipart, but contains non file upload parts
122       (such as an line part with an alternative encoding or content type) we
123       do our best to try and figure out how the value should be presented.
124       If there's a specified character set we will use that to decode rather
125       than the default encoding set by the application.  However if there are
126       complex headers and we cannot determine the correct way to extra a
127       meaningful value from the upload, in this case any part like this will
128       be represented as an instance of Catalyst::Request::PartData.
129
130       Patches and review of this part of the code welcomed.
131
132   $req->body_params
133       Shortcut for body_parameters.
134
135   $req->content_encoding
136       Shortcut for $req->headers->content_encoding.
137
138   $req->content_length
139       Shortcut for $req->headers->content_length.
140
141   $req->content_type
142       Shortcut for $req->headers->content_type.
143
144   $req->cookie
145       A convenient method to access $req->cookies.
146
147           $cookie  = $c->request->cookie('name');
148           @cookies = $c->request->cookie;
149
150   $req->cookies
151       Returns a reference to a hash containing the cookies.
152
153           print $c->request->cookies->{mycookie}->value;
154
155       The cookies in the hash are indexed by name, and the values are
156       CGI::Simple::Cookie objects.
157
158   $req->header
159       Shortcut for $req->headers->header.
160
161   $req->headers
162       Returns an HTTP::Headers object containing the headers for the current
163       request.
164
165           print $c->request->headers->header('X-Catalyst');
166
167   $req->hostname
168       Returns the hostname of the client. Use "$req->uri->host" to get the
169       hostname of the server.
170
171   $req->input
172       Alias for $req->body.
173
174   $req->query_keywords
175       Contains the keywords portion of a query string, when no '=' signs are
176       present.
177
178           http://localhost/path?some+keywords
179
180           $c->request->query_keywords will contain 'some keywords'
181
182   $req->match
183       This contains the matching part of a Regex action. Otherwise it returns
184       the same as 'action', except for default actions, which return an empty
185       string.
186
187   $req->method
188       Contains the request method ("GET", "POST", "HEAD", etc).
189
190   $req->param
191       Returns GET and POST parameters with a CGI.pm-compatible param method.
192       This is an alternative method for accessing parameters in
193       $c->req->parameters.
194
195           $value  = $c->request->param( 'foo' );
196           @values = $c->request->param( 'foo' );
197           @params = $c->request->param;
198
199       Like CGI, and unlike earlier versions of Catalyst, passing multiple
200       arguments to this method, like this:
201
202           $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
203
204       will set the parameter "foo" to the multiple values "bar", "gorch" and
205       "quxx". Previously this would have added "bar" as another value to
206       "foo" (creating it if it didn't exist before), and "quxx" as another
207       value for "gorch".
208
209       NOTE this is considered a legacy interface and care should be taken
210       when using it. "scalar $c->req->param( 'foo' )" will return only the
211       first "foo" param even if multiple are present; "$c->req->param( 'foo'
212       )" will return a list of as many are present, which can have unexpected
213       consequences when writing code of the form:
214
215           $foo->bar(
216               a => 'b',
217               baz => $c->req->param( 'baz' ),
218           );
219
220       If multiple "baz" parameters are provided this code might corrupt data
221       or cause a hash initialization error. For a more straightforward
222       interface see "$c->req->parameters".
223
224       NOTE Interfaces like this, which are based on CGI and the "param"
225       method are known to cause demonstrated exploits. It is highly
226       recommended that you avoid using this method, and migrate existing code
227       away from it.  Here's a whitepaper of the exploit:
228
229       <http://blog.gerv.net/2014/10/new-class-of-vulnerability-in-perl-web-applications/>
230
231       NOTE Further discussion on IRC indicate that the Catalyst core team
232       from 'back then' were well aware of this hack and this is the main
233       reason we added the new approach to getting parameters in the first
234       place.
235
236       Basically this is an exploit that takes advantage of how \param will do
237       one thing in scalar context and another thing in list context.  This is
238       combined with how Perl chooses to deal with duplicate keys in a hash
239       definition by overwriting the value of existing keys with a new value
240       if the same key shows up again.  Generally you will be vulnerable to
241       this exploit if you are using this method in a direct assignment in a
242       hash, such as with a DBIx::Class create statement.  For example, if you
243       have parameters like:
244
245           user?user=123&foo=a&foo=user&foo=456
246
247       You could end up with extra parameters injected into your method calls:
248
249           $c->model('User')->create({
250             user => $c->req->param('user'),
251             foo => $c->req->param('foo'),
252           });
253
254       Which would look like:
255
256           $c->model('User')->create({
257             user => 123,
258             foo => qw(a user 456),
259           });
260
261       (or to be absolutely clear if you are not seeing it):
262
263           $c->model('User')->create({
264             user => 456,
265             foo => 'a',
266           });
267
268       Possible remediations include scrubbing your parameters with a form
269       validator like HTML::FormHandler or being careful to force scalar
270       context using the scalar keyword:
271
272           $c->model('User')->create({
273             user => scalar($c->req->param('user')),
274             foo => scalar($c->req->param('foo')),
275           });
276
277       Upcoming versions of Catalyst will disable this interface by default
278       and require you to positively enable it should you require it for
279       backwards compatibility reasons.
280
281   $req->parameters
282       Returns a reference to a hash containing GET and POST parameters.
283       Values can be either a scalar or an arrayref containing scalars.
284
285           print $c->request->parameters->{field};
286           print $c->request->parameters->{field}->[0];
287
288       This is the combination of "query_parameters" and "body_parameters".
289
290   $req->params
291       Shortcut for $req->parameters.
292
293   $req->path
294       Returns the path, i.e. the part of the URI after $req->base, for the
295       current request.
296
297           http://localhost/path/foo
298
299           $c->request->path will contain 'path/foo'
300
301   $req->path_info
302       Alias for path, added for compatibility with CGI.
303
304   $req->protocol
305       Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
306       request.
307
308   $req->query_parameters
309   $req->query_params
310       Returns a reference to a hash containing query string (GET) parameters.
311       Values can be either a scalar or an arrayref containing scalars.
312
313           print $c->request->query_parameters->{field};
314           print $c->request->query_parameters->{field}->[0];
315
316   $req->read( [$maxlength] )
317       Reads a chunk of data from the request body. This method is intended to
318       be used in a while loop, reading $maxlength bytes on every call.
319       $maxlength defaults to the size of the request if not specified.
320
321   $req->read_chunk(\$buff, $max)
322       Reads a chunk.
323
324       You have to set MyApp->config(parse_on_demand => 1) to use this
325       directly.
326
327   $req->referer
328       Shortcut for $req->headers->referer. Returns the referring page.
329
330   $req->secure
331       Returns true or false, indicating whether the connection is secure
332       (https). The reliability of $req->secure may depend on your server
333       configuration; Catalyst relies on PSGI to determine whether or not a
334       request is secure (Catalyst looks at psgi.url_scheme), and different
335       PSGI servers may make this determination in different ways (as by
336       directly passing along information from the server, interpreting any of
337       several HTTP headers, or using heuristics of their own).
338
339   $req->captures
340       Returns a reference to an array containing captured args from chained
341       actions or regex captures.
342
343           my @captures = @{ $c->request->captures };
344
345   $req->upload
346       A convenient method to access $req->uploads.
347
348           $upload  = $c->request->upload('field');
349           @uploads = $c->request->upload('field');
350           @fields  = $c->request->upload;
351
352           for my $upload ( $c->request->upload('field') ) {
353               print $upload->filename;
354           }
355
356   $req->uploads
357       Returns a reference to a hash containing uploads. Values can be either
358       a Catalyst::Request::Upload object, or an arrayref of
359       Catalyst::Request::Upload objects.
360
361           my $upload = $c->request->uploads->{field};
362           my $upload = $c->request->uploads->{field}->[0];
363
364   $req->uri
365       Returns a URI object for the current request. Stringifies to the URI
366       text.
367
368   $req->mangle_params( { key => 'value' }, $appendmode);
369       Returns a hashref of parameters stemming from the current request's
370       params, plus the ones supplied.  Keys for which no current param exists
371       will be added, keys with undefined values will be removed and keys with
372       existing params will be replaced.  Note that you can supply a true
373       value as the final argument to change behavior with regards to existing
374       parameters, appending values rather than replacing them.
375
376       A quick example:
377
378         # URI query params foo=1
379         my $hashref = $req->mangle_params({ foo => 2 });
380         # Result is query params of foo=2
381
382       versus append mode:
383
384         # URI query params foo=1
385         my $hashref = $req->mangle_params({ foo => 2 }, 1);
386         # Result is query params of foo=1&foo=2
387
388       This is the code behind "uri_with".
389
390   $req->uri_with( { key => 'value' } );
391       Returns a rewritten URI object for the current request. Key/value pairs
392       passed in will override existing parameters. You can remove an existing
393       parameter by passing in an undef value. Unmodified pairs will be
394       preserved.
395
396       You may also pass an optional second parameter that puts "uri_with"
397       into append mode:
398
399         $req->uri_with( { key => 'value' }, { mode => 'append' } );
400
401       See "mangle_params" for an explanation of this behavior.
402
403   $req->remote_user
404       Returns the value of the "REMOTE_USER" environment variable.
405
406   $req->user_agent
407       Shortcut to $req->headers->user_agent. Returns the user agent (browser)
408       version string.
409
410   $req->io_fh
411       Returns a psgix.io bidirectional socket, if your server supports one.
412       Used for when you want to jailbreak out of PSGI and handle
413       bidirectional client server communication manually, such as when you
414       are using cometd or websockets.
415

SETUP METHODS

417       You should never need to call these yourself in application code,
418       however they are useful if extending Catalyst by applying a request
419       role.
420
421   $self->prepare_headers()
422       Sets up the "$res->headers" accessor.
423
424   $self->prepare_body()
425       Sets up the body using HTTP::Body
426
427   $self->prepare_body_chunk()
428       Add a chunk to the request body.
429
430   $self->prepare_body_parameters()
431       Sets up parameters from body.
432
433   $self->prepare_cookies()
434       Parse cookies from header. Sets up a CGI::Simple::Cookie object.
435
436   $self->prepare_connection()
437       Sets up various fields in the request like the local and remote
438       addresses, request method, hostname requested etc.
439
440   $self->prepare_parameters()
441       Ensures that the body has been parsed, then builds the parameters,
442       which are combined from those in the request and those in the body.
443
444       If parameters have already been set will clear the parameters and build
445       them again.
446
447   $self->env
448       Access to the raw PSGI env.
449
450   meta
451       Provided by Moose
452

AUTHORS

454       Catalyst Contributors, see Catalyst.pm
455
457       This library is free software. You can redistribute it and/or modify it
458       under the same terms as Perl itself.
459
460
461
462perl v5.38.0                      2023-07-24              Catalyst::Request(3)
Impressum