1Dancer::Request(3)    User Contributed Perl Documentation   Dancer::Request(3)
2
3
4

NAME

6       Dancer::Request - interface for accessing incoming requests
7

VERSION

9       version 1.3513
10

DESCRIPTION

12       This class implements a common interface for accessing incoming
13       requests in a Dancer application.
14
15       In a route handler, the current request object can be accessed by the
16       "request" method, like in the following example:
17
18           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
25       A route handler should not read the environment by itself, but should
26       instead use the current request object.
27

PUBLIC INTERFACE

29   new()
30       The constructor of the class, used internally by Dancer's core to
31       create request objects.
32
33       It uses the environment hash table given to build the request object:
34
35           Dancer::Request->new(env => \%ENV);
36
37       It also accepts the "is_forward" boolean flag, if the new request
38       object is the result of a forward.
39
40   init()
41       Used internally to define some default values and parse parameters.
42
43   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
47   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
52       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
59   is_forward
60       Flag that will be set to true if the request has been forwarded.
61
62   to_string()
63       Return a string representing the request object (eg: "GET /some/path")
64
65   method()
66       Return the HTTP method used by the client to access the application.
67
68       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
72   address()
73       Return the IP address of the client.
74
75   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
79   protocol()
80       Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
81
82   port()
83       Return the port of the server.
84
85   uri()
86       An alias to request_uri()
87
88   request_uri()
89       Return the raw, undecoded request URI path.
90
91   user()
92       Return remote user if defined.
93
94   script_name()
95       Return script_name from the environment.
96
97   scheme()
98       Return the scheme of the request
99
100   secure()
101       Return true of false, indicating whether the connection is secure
102
103   is_get()
104       Return true if the method requested by the client is 'GET'
105
106   is_head()
107       Return true if the method requested by the client is 'HEAD'
108
109   is_patch()
110       Return true if the method requested by the client is 'PATCH'
111
112   is_post()
113       Return true if the method requested by the client is 'POST'
114
115   is_put()
116       Return true if the method requested by the client is 'PUT'
117
118   is_delete()
119       Return true if the method requested by the client is 'DELETE'
120
121   path()
122       Return the path requested by the client.
123
124   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
128   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
132       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
136           <link rel="stylesheet" href="<% request.uri_base %>/css/style.css" />
137
138   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
145   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
150       So, you can use, for instance:
151
152           my $foo = params->{foo}
153
154       If called in list context, returns a list of key => value pairs, so you
155       could use:
156
157           my %allparams = params;
158
159       If the incoming form data contains multiple values for the same key,
160       they will be returned as an arrayref.
161
162       Fetching only params from a given source
163
164       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
168       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
171       If you want to see only params from a given source, you can say so by
172       passing the $source param to "params()":
173
174           my %querystring_params = params('query');
175           my %route_params       = params('route');
176           my %post_params        = params('body');
177
178       If source equals "route", then only params parsed from the route
179       pattern are returned.
180
181       If source equals "query", then only params parsed from the query string
182       are returned.
183
184       If source equals "body", then only params sent in the request body will
185       be returned.
186
187       If another value is given for $source, then an exception is triggered.
188
189   Vars
190       Alias to the "params" accessor, for backward-compatibility with "CGI"
191       interface.
192
193   request_method
194       Alias to the "method" accessor, for backward-compatibility with "CGI"
195       interface.
196
197   input_handle
198       Alias to the PSGI input handle ("<request->env->{psgi.input}>")
199
200   content_type()
201       Return the content type of the request.
202
203   content_length()
204       Return the content length of the request.
205
206   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
211   headers()
212       Returns the HTTP::Header object used to store all the headers.
213
214   body()
215       Return the raw body of the request, unparsed.
216
217       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
227       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
234   is_ajax()
235       Return true if the value of the header "X-Requested-With" is
236       XMLHttpRequest.
237
238   env()
239       Return the current environment as a hashref.
240
241       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
246   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
251       You should probably use the "upload($name)" accessor instead of
252       manually accessing the "uploads" hash table.
253
254   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
259       If you have many file uploads under the same name, and call
260       "upload('name')" in an array context, the accessor will unroll the
261       ARRAY ref for you:
262
263           my @uploads = request->upload('many_uploads'); # OK
264
265       Whereas with a manual access to the hash table, you'll end up with one
266       element in @uploads, being the ARRAY ref:
267
268           my @uploads = request->uploads->{'many_uploads'}; # $uploads[0]: ARRAY(0xXXXXX)
269
270       That is why this accessor should be used instead of a manual access to
271       "uploads".
272

Values

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
277         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

HTTP environment variables

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
294       "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
304       "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
310       "keep_alive"
311       "path_info"
312       "referer"
313       "remote_address"
314       "request_base"
315       "user_agent"
316

AUTHORS

318       This module has been written by Alexis Sukrieh and was mostly inspired
319       by Plack::Request, written by Tatsuiko Miyagawa.
320
321       Tatsuiko Miyagawa also gave a hand for the PSGI interface.
322

LICENCE

324       This module is released under the same terms as Perl itself.
325

SEE ALSO

327       Dancer
328

AUTHOR

330       Dancer Core Developers
331
333       This software is copyright (c) 2010 by Alexis Sukrieh.
334
335       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.
337
338
339
340perl v5.34.0                      2022-01-21                Dancer::Request(3)
Impressum