1Catalyst::Request(3) User Contributed Perl Documentation Catalyst::Request(3)
2
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 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 $req->arguments
60 Returns a reference to an array containing the arguments.
61 print $c->request->arguments->[0];
63 For example, if your action was
65 package MyApp::Controller::Foo;
67 sub moose : Local {
69 ...
70 }
71 and the URI for the request was "http://.../foo/moose/bah", the string
73 "bah" would be the first and only argument.
74 Arguments get automatically URI-unescaped for you.
76 $req->args
78 Shortcut for "arguments".
79 $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 If your application was queried with the URI
87 "http://localhost:3000/some/path" then "base" is
88 "http://localhost:3000/".
89 $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 $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 You may define addition data_handlers via a global configuration
103 setting. See "Catalyst\DATA HANDLERS" for more information.
104 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 If the body content type does not match an available data handler, this
110 will also raise an exception.
111 $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 print $c->request->body_parameters->{field};
117 print $c->request->body_parameters->{field}->[0];
118 These are the parameters from the POST part of the request, if any.
120 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 Patches and review of this part of the code welcomed.
131 $req->body_params
133 Shortcut for body_parameters.
134 $req->content_encoding
136 Shortcut for $req->headers->content_encoding.
137 $req->content_length
139 Shortcut for $req->headers->content_length.
140 $req->content_type
142 Shortcut for $req->headers->content_type.
143 $req->cookie
145 A convenient method to access $req->cookies.
146 $cookie = $c->request->cookie('name');
148 @cookies = $c->request->cookie;
149 $req->cookies
151 Returns a reference to a hash containing the cookies.
152 print $c->request->cookies->{mycookie}->value;
154 The cookies in the hash are indexed by name, and the values are
156 CGI::Simple::Cookie objects.
157 $req->header
159 Shortcut for $req->headers->header.
160 $req->headers
162 Returns an HTTP::Headers object containing the headers for the current
163 request.
164 print $c->request->headers->header('X-Catalyst');
166 $req->hostname
168 Returns the hostname of the client. Use "$req->uri->host" to get the
169 hostname of the server.
170 $req->input
172 Alias for $req->body.
173 $req->query_keywords
175 Contains the keywords portion of a query string, when no '=' signs are
176 present.
177 http://localhost/path?some+keywords
179 $c->request->query_keywords will contain 'some keywords'
181 $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 $req->method
188 Contains the request method ("GET", "POST", "HEAD", etc).
189 $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 $value = $c->request->param( 'foo' );
196 @values = $c->request->param( 'foo' );
197 @params = $c->request->param;
198 Like CGI, and unlike earlier versions of Catalyst, passing multiple
200 arguments to this method, like this:
201 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
203 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 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 $foo->bar(
216 a => 'b',
217 baz => $c->req->param( 'baz' ),
218 );
219 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 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 <http://blog.gerv.net/2014/10/new-class-of-vulnerability-in-perl-web-applications/>
230 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 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 user?user=123&foo=a&foo=user&foo=456
246 You could end up with extra parameters injected into your method calls:
248 $c->model('User')->create({
250 user => $c->req->param('user'),
251 foo => $c->req->param('foo'),
252 });
253 Which would look like:
255 $c->model('User')->create({
257 user => 123,
258 foo => qw(a user 456),
259 });
260 (or to be absolutely clear if you are not seeing it):
262 $c->model('User')->create({
264 user => 456,
265 foo => 'a',
266 });
267 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 $c->model('User')->create({
273 user => scalar($c->req->param('user')),
274 foo => scalar($c->req->param('foo')),
275 });
276 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 $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 print $c->request->parameters->{field};
286 print $c->request->parameters->{field}->[0];
287 This is the combination of "query_parameters" and "body_parameters".
289 $req->params
291 Shortcut for $req->parameters.
292 $req->path
294 Returns the path, i.e. the part of the URI after $req->base, for the
295 current request.
296 http://localhost/path/foo
298 $c->request->path will contain 'path/foo'
300 $req->path_info
302 Alias for path, added for compatibility with CGI.
303 $req->protocol
305 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
306 request.
307 $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 print $c->request->query_parameters->{field};
314 print $c->request->query_parameters->{field}->[0];
315 $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 $req->read_chunk(\$buff, $max)
322 Reads a chunk.
323 You have to set MyApp->config(parse_on_demand => 1) to use this
325 directly.
326 $req->referer
328 Shortcut for $req->headers->referer. Returns the referring page.
329 $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 $req->captures
340 Returns a reference to an array containing captured args from chained
341 actions or regex captures.
342 my @captures = @{ $c->request->captures };
344 $req->upload
346 A convenient method to access $req->uploads.
347 $upload = $c->request->upload('field');
349 @uploads = $c->request->upload('field');
350 @fields = $c->request->upload;
351 for my $upload ( $c->request->upload('field') ) {
353 print $upload->filename;
354 }
355 $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 my $upload = $c->request->uploads->{field};
362 my $upload = $c->request->uploads->{field}->[0];
363 $req->uri
365 Returns a URI object for the current request. Stringifies to the URI
366 text.
367 $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 A quick example:
377 # URI query params foo=1
379 my $hashref = $req->mangle_params({ foo => 2 });
380 # Result is query params of foo=2
381 versus append mode:
383 # 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 This is the code behind "uri_with".
389 $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 You may also pass an optional second parameter that puts "uri_with"
397 into append mode:
398 $req->uri_with( { key => 'value' }, { mode => 'append' } );
400 See "mangle_params" for an explanation of this behavior.
402 $req->remote_user
404 Returns the value of the "REMOTE_USER" environment variable.
405 $req->user_agent
407 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
408 version string.
409 $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
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 $self->prepare_headers()
422 Sets up the "$res->headers" accessor.
423 $self->prepare_body()
425 Sets up the body using HTTP::Body
426 $self->prepare_body_chunk()
428 Add a chunk to the request body.
429 $self->prepare_body_parameters()
431 Sets up parameters from body.
432 $self->prepare_cookies()
434 Parse cookies from header. Sets up a CGI::Simple::Cookie object.
435 $self->prepare_connection()
437 Sets up various fields in the request like the local and remote
438 addresses, request method, hostname requested etc.
439 $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 If parameters have already been set will clear the parameters and build
445 them again.
446 $self->env
448 Access to the raw PSGI env.
449 meta
451 Provided by Moose
452
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.
459perl v5.38.0 2023-07-24 Catalyst::Request(3)