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 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 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 If the POSTed content type does not match an available data handler,
109 this will also raise an exception.
110 $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 print $c->request->body_parameters->{field};
116 print $c->request->body_parameters->{field}->[0];
117 These are the parameters from the POST part of the request, if any.
119 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 Patches and review of this part of the code welcomed.
130 $req->body_params
132 Shortcut for body_parameters.
133 $req->content_encoding
135 Shortcut for $req->headers->content_encoding.
136 $req->content_length
138 Shortcut for $req->headers->content_length.
139 $req->content_type
141 Shortcut for $req->headers->content_type.
142 $req->cookie
144 A convenient method to access $req->cookies.
145 $cookie = $c->request->cookie('name');
147 @cookies = $c->request->cookie;
148 $req->cookies
150 Returns a reference to a hash containing the cookies.
151 print $c->request->cookies->{mycookie}->value;
153 The cookies in the hash are indexed by name, and the values are
155 CGI::Simple::Cookie objects.
156 $req->header
158 Shortcut for $req->headers->header.
159 $req->headers
161 Returns an HTTP::Headers object containing the headers for the current
162 request.
163 print $c->request->headers->header('X-Catalyst');
165 $req->hostname
167 Returns the hostname of the client. Use "$req->uri->host" to get the
168 hostname of the server.
169 $req->input
171 Alias for $req->body.
172 $req->query_keywords
174 Contains the keywords portion of a query string, when no '=' signs are
175 present.
176 http://localhost/path?some+keywords
178 $c->request->query_keywords will contain 'some keywords'
180 $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 $req->method
187 Contains the request method ("GET", "POST", "HEAD", etc).
188 $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 $value = $c->request->param( 'foo' );
195 @values = $c->request->param( 'foo' );
196 @params = $c->request->param;
197 Like CGI, and unlike earlier versions of Catalyst, passing multiple
199 arguments to this method, like this:
200 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
202 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 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 $foo->bar(
215 a => 'b',
216 baz => $c->req->param( 'baz' ),
217 );
218 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 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 <http://blog.gerv.net/2014/10/new-class-of-vulnerability-in-perl-web-applications/>
229 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 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 user?user=123&foo=a&foo=user&foo=456
245 You could end up with extra parameters injected into your method calls:
247 $c->model('User')->create({
249 user => $c->req->param('user'),
250 foo => $c->req->param('foo'),
251 });
252 Which would look like:
254 $c->model('User')->create({
256 user => 123,
257 foo => qw(a user 456),
258 });
259 (or to be absolutely clear if you are not seeing it):
261 $c->model('User')->create({
263 user => 456,
264 foo => 'a',
265 });
266 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 $c->model('User')->create({
272 user => scalar($c->req->param('user')),
273 foo => scalar($c->req->param('foo')),
274 });
275 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 $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 print $c->request->parameters->{field};
285 print $c->request->parameters->{field}->[0];
286 This is the combination of "query_parameters" and "body_parameters".
288 $req->params
290 Shortcut for $req->parameters.
291 $req->path
293 Returns the path, i.e. the part of the URI after $req->base, for the
294 current request.
295 http://localhost/path/foo
297 $c->request->path will contain 'path/foo'
299 $req->path_info
301 Alias for path, added for compatibility with CGI.
302 $req->protocol
304 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
305 request.
306 $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 print $c->request->query_parameters->{field};
313 print $c->request->query_parameters->{field}->[0];
314 $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 $req->read_chunk(\$buff, $max)
321 Reads a chunk.
322 You have to set MyApp->config(parse_on_demand => 1) to use this
324 directly.
325 $req->referer
327 Shortcut for $req->headers->referer. Returns the referring page.
328 $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 $req->captures
339 Returns a reference to an array containing captured args from chained
340 actions or regex captures.
341 my @captures = @{ $c->request->captures };
343 $req->upload
345 A convenient method to access $req->uploads.
346 $upload = $c->request->upload('field');
348 @uploads = $c->request->upload('field');
349 @fields = $c->request->upload;
350 for my $upload ( $c->request->upload('field') ) {
352 print $upload->filename;
353 }
354 $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 my $upload = $c->request->uploads->{field};
361 my $upload = $c->request->uploads->{field}->[0];
362 $req->uri
364 Returns a URI object for the current request. Stringifies to the URI
365 text.
366 $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 A quick example:
376 # URI query params foo=1
378 my $hashref = $req->mangle_params({ foo => 2 });
379 # Result is query params of foo=2
380 versus append mode:
382 # 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 This is the code behind "uri_with".
388 $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 You may also pass an optional second parameter that puts "uri_with"
396 into append mode:
397 $req->uri_with( { key => 'value' }, { mode => 'append' } );
399 See "mangle_params" for an explanation of this behavior.
401 $req->remote_user
403 Returns the value of the "REMOTE_USER" environment variable.
404 $req->user_agent
406 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
407 version string.
408 $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 $self->prepare_headers()
421 Sets up the "$res->headers" accessor.
422 $self->prepare_body()
424 Sets up the body using HTTP::Body
425 $self->prepare_body_chunk()
427 Add a chunk to the request body.
428 $self->prepare_body_parameters()
430 Sets up parameters from body.
431 $self->prepare_cookies()
433 Parse cookies from header. Sets up a CGI::Simple::Cookie object.
434 $self->prepare_connection()
436 Sets up various fields in the request like the local and remote
437 addresses, request method, hostname requested etc.
438 $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 If parameters have already been set will clear the parameters and build
444 them again.
445 $self->env
447 Access to the raw PSGI env.
448 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.
458perl v5.30.1 2020-01-29 Catalyst::Request(3)