1Dancer2::Core::Request(U3s)er Contributed Perl DocumentatDiaonncer2::Core::Request(3)
2
3
4

NAME

6       Dancer2::Core::Request - Interface for accessing incoming requests
7

VERSION

9       version 0.300004
10

SYNOPSIS

12       In a route handler, the current request object can be accessed by the
13       "request" keyword:
14
15           get '/foo' => sub {
16               request->params; # request, params parsed as a hash ref
17               request->body;   # returns the request body, unparsed
18               request->path;   # the path requested by the client
19               # ...
20           };
21

DESCRIPTION

23       An object representing a Dancer2 request. It aims to provide a proper
24       interface to anything you might need from a web request.
25

METHODS

27   address
28       Return the IP address of the client.
29
30   base
31       Returns an absolute URI for the base of the application.  Returns a URI
32       object (which stringifies to the URL, as you'd expect).
33
34   body_parameters
35       Returns a Hash::MultiValue object representing the POST parameters.
36
37   body
38       Return the raw body of the request, unparsed.
39
40       If you need to access the body of the request, you have to use this
41       accessor and should not try to read "psgi.input" by hand.
42       "Dancer2::Core::Request" already did it for you and kept the raw body
43       untouched in there.
44
45   content
46       Returns the undecoded byte string POST body.
47
48   cookies
49       Returns a reference to a hash containing cookies, where the keys are
50       the names of the cookies and values are Dancer2::Core::Cookie objects.
51
52   data
53       If the application has a serializer and if the request has serialized
54       content, returns the deserialized structure as a hashref.
55
56   dispatch_path
57       Alias for path. Deprecated.
58
59   env
60       Return the current PSGI environment hash reference.
61
62   header($name)
63       Return the value of the given header, if present. If the header has
64       multiple values, returns an the list of values if called in list
65       context, the first one in scalar.
66
67   headers
68       Returns either an HTTP::Headers or an HTTP::Headers::Fast object
69       representing the headers.
70
71   id
72       The ID of the request. This allows you to trace a specific request in
73       loggers, per the string created using "to_string".
74
75       The ID of the request is essentially the number of requests run in the
76       current class.
77
78   input
79       Alias to "input_handle" method below.
80
81   input_handle
82       Alias to the PSGI input handle ("<request->env->{psgi.input}>")
83
84   is_ajax
85       Return true if the value of the header "X-Requested-With" is
86       "XMLHttpRequest".
87
88   is_delete
89       Return true if the method requested by the client is 'DELETE'
90
91   is_get
92       Return true if the method requested by the client is 'GET'
93
94   is_head
95       Return true if the method requested by the client is 'HEAD'
96
97   is_post
98       Return true if the method requested by the client is 'POST'
99
100   is_put
101       Return true if the method requested by the client is 'PUT'
102
103   is_options
104       Return true if the method requested by the client is 'OPTIONS'
105
106   logger
107       Returns the "psgix.logger" code reference, if exists.
108
109   method
110       Return the HTTP method used by the client to access the application.
111
112       While this method returns the method string as provided by the
113       environment, it's better to use one of the following boolean accessors
114       if you want to inspect the requested method.
115
116   new
117       The constructor of the class, used internally by Dancer2's core to
118       create request objects.
119
120       It uses the environment hash table given to build the request object:
121
122           Dancer2::Core::Request->new( env => $env );
123
124       There are two additional parameters for instantiation:
125
126       ·   serializer
127
128           A serializer object to work with when reading the request body.
129
130       ·   body_params
131
132           Provide body parameters.
133
134           Used internally when we need to avoid parsing the body again.
135
136   param($key)
137       Calls the "params" method below and fetches the key provided.
138
139   params($source)
140       Called in scalar context, returns a hashref of params, either from the
141       specified source (see below for more info on that) or merging all
142       sources.
143
144       So, you can use, for instance:
145
146           my $foo = params->{foo}
147
148       If called in list context, returns a list of key and value pairs, so
149       you could use:
150
151           my %allparams = params;
152
153       Parameters are merged in the following order: query, body, route - i.e.
154       route parameters have the highest priority:
155
156           POST /hello/Ruth?name=Quentin
157
158           name=Bobbie
159
160           post '/hello/:name' => sub {
161               return "Hello, " . route_parameters->get('name') . "!"; # returns Ruth
162               return "Hello, " . query_parameters->get('name') . "!"; # returns Quentin
163               return "Hello, " . body_parameters->get('name') . "!";  # returns Bobbie
164               return "Hello, " . param('name') . "!";                 # returns Ruth
165           };
166
167       The "query_parameters", "route_parameters", and "body_parameters"
168       keywords provide a Hash::MultiValue result from the three different
169       parameters.  We recommend using these rather than "params", because of
170       the potential for unintentional behaviour - consider the following
171       request and route handler:
172
173           POST /artist/104/new-song
174
175           name=Careless Dancing
176
177           post '/artist/:id/new-song' => sub {
178             find_artist(param('id'))->create_song(params);
179             # oops! we just passed id into create_song,
180             # but we probably only intended to pass name
181             find_artist(param('id'))->create_song(body_parameters);
182           };
183
184           POST /artist/104/join-band
185
186           id=4
187           name=Dancing Misfits
188
189           post '/artist/:id/new-song' => sub {
190             find_artist(param('id'))->join_band(params);
191             # oops! we just passed an id of 104 into join_band,
192             # but we probably should have passed an id of 4
193           };
194
195   parameters
196       Returns a Hash::MultiValue object with merged GET and POST parameters.
197
198       Parameters are merged in the following order: query, body, route - i.e.
199       route parameters have the highest priority - see "params" for how this
200       works, and associated risks and alternatives.
201
202   path
203       The path requested by the client, normalized. This is effectively
204       "path_info" or a single forward "/".
205
206   path_info
207       The raw requested path. This could be empty. Use "path" instead.
208
209   port
210       Return the port of the server.
211
212   protocol
213       Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
214
215   query_parameters
216       Returns a Hash::MultiValue parameters object.
217
218   query_string
219       Returns the portion of the request defining the query itself - this is
220       what comes after the "?" in a URI.
221
222   raw_body
223       Alias to "content" method.
224
225   remote_address
226       Alias for "address" method.
227
228   remote_host
229       Return the remote host of the client. This only works with web servers
230       configured to do a reverse DNS lookup on the client's IP address.
231
232   request_method
233       Alias to the "method" accessor, for backward-compatibility with "CGI"
234       interface.
235
236   request_uri
237       Return the raw, undecoded request URI path.
238
239   route
240       Return the route which this request matched.
241
242   scheme
243       Return the scheme of the request
244
245   script_name
246       Return script_name from the environment.
247
248   secure
249       Return true or false, indicating whether the connection is secure -
250       this is effectively checking if the scheme is HTTPS or not.
251
252   serializer
253       Returns the optional serializer object used to deserialize request
254       parameters.
255
256   session
257       Returns the "psgix.session" hash, if exists.
258
259   session_options
260       Returns the "psgix.session.options" hash, if exists.
261
262   to_string
263       Return a string representing the request object (e.g., "GET
264       /some/path").
265
266   upload($name)
267       Context-aware accessor for uploads. It's a wrapper around an access to
268       the hash table provided by "uploads()". It looks at the calling context
269       and returns a corresponding value.
270
271       If you have many file uploads under the same name, and call
272       "upload('name')" in an array context, the accessor will unroll the
273       ARRAY ref for you:
274
275           my @uploads = request->upload('many_uploads'); # OK
276
277       Whereas with a manual access to the hash table, you'll end up with one
278       element in @uploads, being the arrayref:
279
280           my @uploads = request->uploads->{'many_uploads'};
281           # $uploads[0]: ARRAY(0xXXXXX)
282
283       That is why this accessor should be used instead of a manual access to
284       "uploads".
285
286   uploads
287       Returns a reference to a hash containing uploads. Values can be either
288       a Dancer2::Core::Request::Upload object, or an arrayref of
289       Dancer2::Core::Request::Upload objects.
290
291       You should probably use the "upload($name)" accessor instead of
292       manually accessing the "uploads" hash table.
293
294   uri
295       An alias to "request_uri".
296
297   uri_base
298       Same thing as "base" above, except it removes the last trailing slash
299       in the path if it is the only path.
300
301       This means that if your base is http://myserver/, "uri_base" will
302       return http://myserver (notice no trailing slash). This is considered
303       very useful when using templates to do the following thing:
304
305           <link rel="stylesheet" href="[% request.uri_base %]/css/style.css" />
306
307   uri_for(path, params)
308       Constructs a URI from the base and the passed path. If params (hashref)
309       is supplied, these are added to the query string of the URI.
310
311       Thus, with the following base:
312
313           http://localhost:5000/foo
314
315       You get the following behavior:
316
317           my $uri = request->uri_for('/bar', { baz => 'baz' });
318           print $uri; # http://localhost:5000/foo/bar?baz=baz
319
320       "uri_for" returns a URI object (which can stringify to the value).
321
322   user
323       Return remote user if defined.
324
325   var
326       By-name interface to variables stored in this request object.
327
328         my $stored = $request->var('some_variable');
329
330       returns the value of 'some_variable', while
331
332         $request->var('some_variable' => 'value');
333
334       will set it.
335
336   vars
337       Access to the internal hash of variables:
338
339           my $value = $request->vars->{'my_key'};
340
341       You want to use "var" above.
342

Common HTTP request headers

344       Commonly used client-supplied HTTP request headers are available
345       through specific accessors:
346
347       "accept"
348           HTTP header: "HTTP_ACCEPT".
349
350       "accept_charset"
351           HTTP header: "HTTP_ACCEPT_CHARSET".
352
353       "accept_encoding"
354           HTTP header: "HTTP_ACCEPT_ENCODING".
355
356       "accept_language"
357           HTTP header: "HTTP_ACCEPT_LANGUAGE".
358
359       "agent"
360           Alias for "user_agent") below.
361
362       "connection"
363           HTTP header: "HTTP_CONNECTION".
364
365       "content_encoding"
366           HTTP header: "HTTP_CONTENT_ENCODING".
367
368       "content_length"
369           HTTP header: "HTTP_CONTENT_LENGTH".
370
371       "content_type"
372           HTTP header: "HTTP_CONTENT_TYPE".
373
374       "forwarded_for_address"
375           HTTP header: "HTTP_X_FORWARDED_FOR".
376
377       "forwarded_host"
378           HTTP header: "HTTP_X_FORWARDED_HOST".
379
380       "forwarded_protocol"
381           One of either "HTTP_X_FORWARDED_PROTOCOL",
382           "HTTP_X_FORWARDED_PROTO", or "HTTP_FORWARDED_PROTO".
383
384       "host"
385           Checks whether we are behind a proxy using the "behind_proxy"
386           configuration option, and if so returns the first
387           "HTTP_X_FORWARDED_HOST", since this is a comma separated list.
388
389           If you have not configured that you are behind a proxy, it returns
390           HTTP header "HTTP_HOST".
391
392       "keep_alive"
393           HTTP header: "HTTP_KEEP_ALIVE".
394
395       "referer"
396           HTTP header: "HTTP_REFERER".
397
398       "user_agent"
399           HTTP header: "HTTP_USER_AGENT".
400
401       "x_requested_with"
402           HTTP header: "HTTP_X_REQUESTED_WITH".
403

Fetching only params from a given source

405       If a required source isn't specified, a mixed hashref (or list of key
406       value pairs, in list context) will be returned; this will contain
407       params from all sources (route, query, body).
408
409       In practical terms, this means that if the param "foo" is passed both
410       on the querystring and in a POST body, you can only access one of them.
411
412       If you want to see only params from a given source, you can say so by
413       passing the $source param to "params()":
414
415           my %querystring_params = params('query');
416           my %route_params       = params('route');
417           my %post_params        = params('body');
418
419       If source equals "route", then only params parsed from the route
420       pattern are returned.
421
422       If source equals "query", then only params parsed from the query string
423       are returned.
424
425       If source equals "body", then only params sent in the request body will
426       be returned.
427
428       If another value is given for $source, then an exception is triggered.
429

EXTRA SPEED

431       If Dancer2::Core::Request detects the following modules as installed,
432       it will use them to speed things up:
433
434       ·   URL::Encode::XS
435
436       ·   CGI::Deurl::XS
437

AUTHOR

439       Dancer Core Developers
440
442       This software is copyright (c) 2020 by Alexis Sukrieh.
443
444       This is free software; you can redistribute it and/or modify it under
445       the same terms as the Perl 5 programming language system itself.
446
447
448
449perl v5.32.0                      2020-07-28         Dancer2::Core::Request(3)
Impressum