1Dancer::Request(3) User Contributed Perl Documentation Dancer::Request(3)
2
6 Dancer::Request - interface for accessing incoming requests
7
9 version 1.3521
10
12 This class implements a common interface for accessing incoming
13 requests in a Dancer application.
14 In a route handler, the current request object can be accessed by the
16 "request" method, like in the following example:
17 get '/foo' => sub {
19 request->params; # request, params parsed as a hash ref
20 request->body; # returns the request body, unparsed
21 request->path; # the path requested by the client
22 # ...
23 };
24 A route handler should not read the environment by itself, but should
26 instead use the current request object.
27
29 new()
30 The constructor of the class, used internally by Dancer's core to
31 create request objects.
32 It uses the environment hash table given to build the request object:
34 Dancer::Request->new(env => \%ENV);
36 It also accepts the "is_forward" boolean flag, if the new request
38 object is the result of a forward.
39 init()
41 Used internally to define some default values and parse parameters.
42 new_for_request($method, $path, $params, $body, $headers)
44 An alternate constructor convenient for test scripts which creates a
45 request object with the arguments given.
46 forward($request, $new_location)
48 Create a new request which is a clone of the current one, apart from
49 the path location, which points instead to the new location. This is
50 used internally to chain requests using the forward keyword.
51 Note that the new location should be a hash reference. Only one key is
53 required, the "to_url", that should point to the URL that forward will
54 use. Optional values are the key "params" to a hash of parameters to be
55 added to the current request parameters, and the key "options" that
56 points to a hash of options about the redirect (for instance, "method"
57 pointing to a new request method).
58 is_forward
60 Flag that will be set to true if the request has been forwarded.
61 to_string()
63 Return a string representing the request object (eg: "GET /some/path")
64 method()
66 Return the HTTP method used by the client to access the application.
67 While this method returns the method string as provided by the
69 environment, it's better to use one of the following boolean accessors
70 if you want to inspect the requested method.
71 address()
73 Return the IP address of the client.
74 remote_host()
76 Return the remote host of the client. This only works with web servers
77 configured to do a reverse DNS lookup on the client's IP address.
78 protocol()
80 Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
81 port()
83 Return the port of the server.
84 uri()
86 An alias to request_uri()
87 request_uri()
89 Return the raw, undecoded request URI path.
90 user()
92 Return remote user if defined.
93 script_name()
95 Return script_name from the environment.
96 scheme()
98 Return the scheme of the request
99 secure()
101 Return true of false, indicating whether the connection is secure
102 is_get()
104 Return true if the method requested by the client is 'GET'
105 is_head()
107 Return true if the method requested by the client is 'HEAD'
108 is_patch()
110 Return true if the method requested by the client is 'PATCH'
111 is_post()
113 Return true if the method requested by the client is 'POST'
114 is_put()
116 Return true if the method requested by the client is 'PUT'
117 is_delete()
119 Return true if the method requested by the client is 'DELETE'
120 path()
122 Return the path requested by the client.
123 base()
125 Returns an absolute URI for the base of the application. Returns a URI
126 object (which stringifies to the URL, as you'd expect).
127 uri_base()
129 Same thing as "base" above, except it removes the last trailing slash
130 in the path if it is the only path.
131 This means that if your base is http://myserver/, "uri_base" will
133 return http://myserver (notice no trailing slash). This is considered
134 very useful when using templates to do the following thing:
135 <link rel="stylesheet" href="<% request.uri_base %>/css/style.css" />
137 uri_for(path, params)
139 Constructs a URI from the base and the passed path. If params
140 (hashref) is supplied, these are added to the query string of the uri.
141 If the base is "http://localhost:5000/foo", "request->uri_for('/bar', {
142 baz => 'baz' })" would return "http://localhost:5000/foo/bar?baz=baz".
143 Returns a URI object (which stringifies to the URL, as you'd expect).
144 params($source)
146 Called in scalar context, returns a hashref of params, either from the
147 specified source (see below for more info on that) or merging all
148 sources.
149 So, you can use, for instance:
151 my $foo = params->{foo}
153 If called in list context, returns a list of key => value pairs, so you
155 could use:
156 my %allparams = params;
158 If the incoming form data contains multiple values for the same key,
160 they will be returned as an arrayref.
161 Fetching only params from a given source
163 If a required source isn't specified, a mixed hashref (or list of key
165 value pairs, in list context) will be returned; this will contain
166 params from all sources (route, query, body).
167 In practical terms, this means that if the param "foo" is passed both
169 on the querystring and in a POST body, you can only access one of them.
170 If you want to see only params from a given source, you can say so by
172 passing the $source param to params():
173 my %querystring_params = params('query');
175 my %route_params = params('route');
176 my %post_params = params('body');
177 If source equals "route", then only params parsed from the route
179 pattern are returned.
180 If source equals "query", then only params parsed from the query string
182 are returned.
183 If source equals "body", then only params sent in the request body will
185 be returned.
186 If another value is given for $source, then an exception is triggered.
188 Vars
190 Alias to the "params" accessor, for backward-compatibility with "CGI"
191 interface.
192 request_method
194 Alias to the "method" accessor, for backward-compatibility with "CGI"
195 interface.
196 input_handle
198 Alias to the PSGI input handle ("<request->env->{psgi.input}>")
199 content_type()
201 Return the content type of the request.
202 content_length()
204 Return the content length of the request.
205 header($name)
207 Return the value of the given header, if present. If the header has
208 multiple values, return a list with its values if called in list
209 context, or the first one if called in scalar context.
210 headers()
212 Returns the HTTP::Header object used to store all the headers.
213 body()
215 Return the raw body of the request, unparsed.
216 NOTE: the behaviour of this keyword has changed. Originally, the
218 entire raw request body was kept in RAM for this accessor, but that's
219 not ideal if you handle large requests (file uploads, etc), so in
220 1.3143 that was ditched, and the body accessor replaced by a
221 convenience method which would get the temp file handle that HTTP::Body
222 uses, read it for you and return the content, so that if you did want
223 the raw body, it was there. However, HTTP::Body only creates a temp
224 file for certain types of request, leading to unpredictable behaviour
225 and confusion - see issue #1140.
226 So, handling of the raw request body is now controlled by a
228 configuration setting, raw_request_body_in_ram, which controls whether
229 or not the raw request body will be kept in RAM when it's parsed; if
230 this is set to a false value, then the body accessor will not return
231 anything, giving you lower memory usage, at the cost of not having
232 access to the raw (unparsed) request body.
233 is_ajax()
235 Return true if the value of the header "X-Requested-With" is
236 XMLHttpRequest.
237 env()
239 Return the current environment as a hashref.
240 Note that a request's environment is not always reflected by the global
242 variable %ENV (e.g., when running via Plack::Handler::FCGI). In
243 consequence, it is recommended to always rely on the values returned by
244 env(), and not to access %ENV directly.
245 uploads()
247 Returns a reference to a hash containing uploads. Values can be either
248 a Dancer::Request::Upload object, or an arrayref of
249 Dancer::Request::Upload objects.
250 You should probably use the upload($name) accessor instead of manually
252 accessing the "uploads" hash table.
253 upload($name)
255 Context-aware accessor for uploads. It's a wrapper around an access to
256 the hash table provided by uploads(). It looks at the calling context
257 and returns a corresponding value.
258 If you have many file uploads under the same name, and call
260 upload('name') in an array context, the accessor will unroll the ARRAY
261 ref for you:
262 my @uploads = request->upload('many_uploads'); # OK
264 Whereas with a manual access to the hash table, you'll end up with one
266 element in @uploads, being the ARRAY ref:
267 my @uploads = request->uploads->{'many_uploads'}; # $uploads[0]: ARRAY(0xXXXXX)
269 That is why this accessor should be used instead of a manual access to
271 "uploads".
272
274 Given a request to http://perldancer.org:5000/request-methods?a=1 these
275 are the values returned by the various request-> method calls:
276 base http://perldancer.org:5000/
278 host perldancer.org
279 uri_base http://perldancer.org:5000
280 uri /request-methods?a=1
281 request_uri /request-methods?a=1
282 path /request-methods
283 path_info /request-methods
284 method GET
285 port 5000
286 protocol HTTP/1.1
287 scheme http
288
290 All HTTP environment variables that are in %ENV will be provided in the
291 Dancer::Request object through specific accessors, here are those
292 supported:
293 "accept"
295 "accept_charset"
296 "accept_encoding"
297 "accept_language"
298 "accept_type"
299 "agent" (alias for "user_agent")
300 "connection"
301 "forwarded_for_address"
302 Looks for HTTP_X_FORWARDED_FOR if X_FORWARDED_FOR is not there.
303 "forwarded_protocol"
305 "forwarded_host"
306 "host"
307 If you app is on a non-standard port, you can expect this to return
308 the hostname and port, e.g. "example.com:5000".
309 "keep_alive"
311 "path_info"
312 "referer"
313 "remote_address"
314 "request_base"
315 "user_agent"
316
318 This module has been written by Alexis Sukrieh and was mostly inspired
319 by Plack::Request, written by Tatsuiko Miyagawa.
320 Tatsuiko Miyagawa also gave a hand for the PSGI interface.
322
324 This module is released under the same terms as Perl itself.
325
327 Dancer
328
330 Dancer Core Developers
331
333 This software is copyright (c) 2010 by Alexis Sukrieh.
334 This is free software; you can redistribute it and/or modify it under
336 the same terms as the Perl 5 programming language system itself.
337perl v5.36.0 2023-02-09 Dancer::Request(3)