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->action;
12 $req->address;
13 $req->arguments;
14 $req->args;
15 $req->base;
16 $req->body;
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; # previously knows as snippets
40 $req->upload;
41 $req->uploads;
42 $req->uri;
43 $req->user;
44 $req->user_agent;
45 See also Catalyst, Catalyst::Request::Upload.
47
49 This is the Catalyst Request class, which provides an interface to data
50 for the current client request. The request object is prepared by
51 Catalyst::Engine, thus hiding the details of the particular engine
52 implementation.
53
55 $req->action
56 [DEPRECATED] Returns the name of the requested action.
57 Use "$c->action" instead (which returns a Catalyst::Action object).
59 $req->address
61 Returns the IP address of the client.
62 $req->arguments
64 Returns a reference to an array containing the arguments.
65 print $c->request->arguments->[0];
67 For example, if your action was
69 package MyApp::Controller::Foo;
71 sub moose : Local {
73 ...
74 }
75 and the URI for the request was "http://.../foo/moose/bah", the string
77 "bah" would be the first and only argument.
78 Arguments get automatically URI-unescaped for you.
80 $req->args
82 Shortcut for "arguments".
83 $req->base
85 Contains the URI base. This will always have a trailing slash. Note
86 that the URI scheme (eg., http vs. https) must be determined through
87 heuristics; depending on your server configuration, it may be
88 incorrect. See $req->secure for more info.
89 If your application was queried with the URI
91 "http://localhost:3000/some/path" then "base" is
92 "http://localhost:3000/".
93 $req->body
95 Returns the message body of the request, as returned by HTTP::Body: a
96 string, unless Content-Type is "application/x-www-form-urlencoded",
97 "text/xml", or "multipart/form-data", in which case a File::Temp object
98 is returned.
99 $req->body_parameters
101 Returns a reference to a hash containing body (POST) parameters. Values
102 can be either a scalar or an arrayref containing scalars.
103 print $c->request->body_parameters->{field};
105 print $c->request->body_parameters->{field}->[0];
106 These are the parameters from the POST part of the request, if any.
108 $req->body_params
110 Shortcut for body_parameters.
111 $req->content_encoding
113 Shortcut for $req->headers->content_encoding.
114 $req->content_length
116 Shortcut for $req->headers->content_length.
117 $req->content_type
119 Shortcut for $req->headers->content_type.
120 $req->cookie
122 A convenient method to access $req->cookies.
123 $cookie = $c->request->cookie('name');
125 @cookies = $c->request->cookie;
126 $req->cookies
128 Returns a reference to a hash containing the cookies.
129 print $c->request->cookies->{mycookie}->value;
131 The cookies in the hash are indexed by name, and the values are
133 CGI::Simple::Cookie objects.
134 $req->header
136 Shortcut for $req->headers->header.
137 $req->headers
139 Returns an HTTP::Headers object containing the headers for the current
140 request.
141 print $c->request->headers->header('X-Catalyst');
143 $req->hostname
145 Returns the hostname of the client.
146 $req->input
148 Alias for $req->body.
149 $req->query_keywords
151 Contains the keywords portion of a query string, when no '=' signs are
152 present.
153 http://localhost/path?some+keywords
155 $c->request->query_keywords will contain 'some keywords'
157 $req->match
159 This contains the matching part of a Regex action. Otherwise it returns
160 the same as 'action', except for default actions, which return an empty
161 string.
162 $req->method
164 Contains the request method ("GET", "POST", "HEAD", etc).
165 $req->param
167 Returns GET and POST parameters with a CGI.pm-compatible param method.
168 This is an alternative method for accessing parameters in
169 $c->req->parameters.
170 $value = $c->request->param( 'foo' );
172 @values = $c->request->param( 'foo' );
173 @params = $c->request->param;
174 Like CGI, and unlike earlier versions of Catalyst, passing multiple
176 arguments to this method, like this:
177 $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );
179 will set the parameter "foo" to the multiple values "bar", "gorch" and
181 "quxx". Previously this would have added "bar" as another value to
182 "foo" (creating it if it didn't exist before), and "quxx" as another
183 value for "gorch".
184 NOTE this is considered a legacy interface and care should be taken
186 when using it. "scalar $c->req->param( 'foo' )" will return only the
187 first "foo" param even if multiple are present; "$c->req->param( 'foo'
188 )" will return a list of as many are present, which can have unexpected
189 consequences when writing code of the form:
190 $foo->bar(
192 a => 'b',
193 baz => $c->req->param( 'baz' ),
194 );
195 If multiple "baz" parameters are provided this code might corrupt data
197 or cause a hash initialization error. For a more straightforward
198 interface see "$c->req->parameters".
199 $req->parameters
201 Returns a reference to a hash containing GET and POST parameters.
202 Values can be either a scalar or an arrayref containing scalars.
203 print $c->request->parameters->{field};
205 print $c->request->parameters->{field}->[0];
206 This is the combination of "query_parameters" and "body_parameters".
208 $req->params
210 Shortcut for $req->parameters.
211 $req->path
213 Returns the path, i.e. the part of the URI after $req->base, for the
214 current request.
215 $req->path_info
217 Alias for path, added for compatibility with CGI.
218 $req->protocol
220 Returns the protocol (HTTP/1.0 or HTTP/1.1) used for the current
221 request.
222 $req->query_parameters
224 $req->query_params
225 Returns a reference to a hash containing query string (GET) parameters.
226 Values can be either a scalar or an arrayref containing scalars.
227 print $c->request->query_parameters->{field};
229 print $c->request->query_parameters->{field}->[0];
230 $req->read( [$maxlength] )
232 Reads a chunk of data from the request body. This method is intended to
233 be used in a while loop, reading $maxlength bytes on every call.
234 $maxlength defaults to the size of the request if not specified.
235 You have to set MyApp->config(parse_on_demand => 1) to use this
237 directly.
238 $req->referer
240 Shortcut for $req->headers->referer. Returns the referring page.
241 $req->secure
243 Returns true or false, indicating whether the connection is secure
244 (https). Note that the URI scheme (eg., http vs. https) must be
245 determined through heuristics, and therefore the reliablity of
246 $req->secure will depend on your server configuration. If you are
247 serving secure pages on the standard SSL port (443) and/or setting the
248 HTTPS environment variable, $req->secure should be valid.
249 $req->captures
251 Returns a reference to an array containing captured args from chained
252 actions or regex captures.
253 my @captures = @{ $c->request->captures };
255 $req->snippets
257 "captures" used to be called snippets. This is still available for
258 backwards compatibility, but is considered deprecated.
259 $req->upload
261 A convenient method to access $req->uploads.
262 $upload = $c->request->upload('field');
264 @uploads = $c->request->upload('field');
265 @fields = $c->request->upload;
266 for my $upload ( $c->request->upload('field') ) {
268 print $upload->filename;
269 }
270 $req->uploads
272 Returns a reference to a hash containing uploads. Values can be either
273 a Catalyst::Request::Upload object, or an arrayref of
274 Catalyst::Request::Upload objects.
275 my $upload = $c->request->uploads->{field};
277 my $upload = $c->request->uploads->{field}->[0];
278 $req->uri
280 Returns a URI object for the current request. Stringifies to the URI
281 text.
282 $req->mangle_params( { key => 'value' }, $appendmode);
284 Returns a hashref of parameters stemming from the current request's
285 params, plus the ones supplied. Keys for which no current param exists
286 will be added, keys with undefined values will be removed and keys with
287 existing params will be replaced. Note that you can supply a true
288 value as the final argument to change behavior with regards to existing
289 parameters, appending values rather than replacing them.
290 A quick example:
292 # URI query params foo=1
294 my $hashref = $req->mangle_params({ foo => 2 });
295 # Result is query params of foo=2
296 versus append mode:
298 # URI query params foo=1
300 my $hashref = $req->mangle_params({ foo => 2 }, 1);
301 # Result is query params of foo=1&foo=2
302 This is the code behind "uri_with".
304 $req->uri_with( { key => 'value' } );
306 Returns a rewritten URI object for the current request. Key/value pairs
307 passed in will override existing parameters. You can remove an existing
308 parameter by passing in an undef value. Unmodified pairs will be
309 preserved.
310 You may also pass an optional second parameter that puts "uri_with"
312 into append mode:
313 $req->uri_with( { key => 'value' }, { mode => 'append' } );
315 See "mangle_params" for an explanation of this behavior.
317 $req->remote_user
319 Returns the value of the "REMOTE_USER" environment variable.
320 $req->user_agent
322 Shortcut to $req->headers->user_agent. Returns the user agent (browser)
323 version string.
324 meta
326 Provided by Moose
327
329 Catalyst Contributors, see Catalyst.pm
330
332 This library is free software. You can redistribute it and/or modify it
333 under the same terms as Perl itself.
334perl v5.12.1 2009-12-09 Catalyst::Request(3)