1Dancer2::Core::Request(U3s)er Contributed Perl DocumentatDiaonncer2::Core::Request(3)
2
6 Dancer2::Core::Request - Interface for accessing incoming requests
7
9 version 0.300004
10
12 In a route handler, the current request object can be accessed by the
13 "request" keyword:
14 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
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
27 address
28 Return the IP address of the client.
29 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 body_parameters
35 Returns a Hash::MultiValue object representing the POST parameters.
36 body
38 Return the raw body of the request, unparsed.
39 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 content
46 Returns the undecoded byte string POST body.
47 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 data
53 If the application has a serializer and if the request has serialized
54 content, returns the deserialized structure as a hashref.
55 dispatch_path
57 Alias for path. Deprecated.
58 env
60 Return the current PSGI environment hash reference.
61 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 headers
68 Returns either an HTTP::Headers or an HTTP::Headers::Fast object
69 representing the headers.
70 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 The ID of the request is essentially the number of requests run in the
76 current class.
77 input
79 Alias to "input_handle" method below.
80 input_handle
82 Alias to the PSGI input handle ("<request->env->{psgi.input}>")
83 is_ajax
85 Return true if the value of the header "X-Requested-With" is
86 "XMLHttpRequest".
87 is_delete
89 Return true if the method requested by the client is 'DELETE'
90 is_get
92 Return true if the method requested by the client is 'GET'
93 is_head
95 Return true if the method requested by the client is 'HEAD'
96 is_post
98 Return true if the method requested by the client is 'POST'
99 is_put
101 Return true if the method requested by the client is 'PUT'
102 is_options
104 Return true if the method requested by the client is 'OPTIONS'
105 logger
107 Returns the "psgix.logger" code reference, if exists.
108 method
110 Return the HTTP method used by the client to access the application.
111 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 new
117 The constructor of the class, used internally by Dancer2's core to
118 create request objects.
119 It uses the environment hash table given to build the request object:
121 Dancer2::Core::Request->new( env => $env );
123 There are two additional parameters for instantiation:
125 · serializer
127 A serializer object to work with when reading the request body.
129 · body_params
131 Provide body parameters.
133 Used internally when we need to avoid parsing the body again.
135 param($key)
137 Calls the "params" method below and fetches the key provided.
138 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 So, you can use, for instance:
145 my $foo = params->{foo}
147 If called in list context, returns a list of key and value pairs, so
149 you could use:
150 my %allparams = params;
152 Parameters are merged in the following order: query, body, route - i.e.
154 route parameters have the highest priority:
155 POST /hello/Ruth?name=Quentin
157 name=Bobbie
159 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 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 POST /artist/104/new-song
174 name=Careless Dancing
176 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 POST /artist/104/join-band
185 id=4
187 name=Dancing Misfits
188 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 parameters
196 Returns a Hash::MultiValue object with merged GET and POST parameters.
197 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 path
203 The path requested by the client, normalized. This is effectively
204 "path_info" or a single forward "/".
205 path_info
207 The raw requested path. This could be empty. Use "path" instead.
208 port
210 Return the port of the server.
211 protocol
213 Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
214 query_parameters
216 Returns a Hash::MultiValue parameters object.
217 query_string
219 Returns the portion of the request defining the query itself - this is
220 what comes after the "?" in a URI.
221 raw_body
223 Alias to "content" method.
224 remote_address
226 Alias for "address" method.
227 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 request_method
233 Alias to the "method" accessor, for backward-compatibility with "CGI"
234 interface.
235 request_uri
237 Return the raw, undecoded request URI path.
238 route
240 Return the route which this request matched.
241 scheme
243 Return the scheme of the request
244 script_name
246 Return script_name from the environment.
247 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 serializer
253 Returns the optional serializer object used to deserialize request
254 parameters.
255 session
257 Returns the "psgix.session" hash, if exists.
258 session_options
260 Returns the "psgix.session.options" hash, if exists.
261 to_string
263 Return a string representing the request object (e.g., "GET
264 /some/path").
265 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 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 my @uploads = request->upload('many_uploads'); # OK
276 Whereas with a manual access to the hash table, you'll end up with one
278 element in @uploads, being the arrayref:
279 my @uploads = request->uploads->{'many_uploads'};
281 # $uploads[0]: ARRAY(0xXXXXX)
282 That is why this accessor should be used instead of a manual access to
284 "uploads".
285 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 You should probably use the "upload($name)" accessor instead of
292 manually accessing the "uploads" hash table.
293 uri
295 An alias to "request_uri".
296 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 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 <link rel="stylesheet" href="[% request.uri_base %]/css/style.css" />
306 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 Thus, with the following base:
312 http://localhost:5000/foo
314 You get the following behavior:
316 my $uri = request->uri_for('/bar', { baz => 'baz' });
318 print $uri; # http://localhost:5000/foo/bar?baz=baz
319 "uri_for" returns a URI object (which can stringify to the value).
321 user
323 Return remote user if defined.
324 var
326 By-name interface to variables stored in this request object.
327 my $stored = $request->var('some_variable');
329 returns the value of 'some_variable', while
331 $request->var('some_variable' => 'value');
333 will set it.
335 vars
337 Access to the internal hash of variables:
338 my $value = $request->vars->{'my_key'};
340 You want to use "var" above.
342
344 Commonly used client-supplied HTTP request headers are available
345 through specific accessors:
346 "accept"
348 HTTP header: "HTTP_ACCEPT".
349 "accept_charset"
351 HTTP header: "HTTP_ACCEPT_CHARSET".
352 "accept_encoding"
354 HTTP header: "HTTP_ACCEPT_ENCODING".
355 "accept_language"
357 HTTP header: "HTTP_ACCEPT_LANGUAGE".
358 "agent"
360 Alias for "user_agent") below.
361 "connection"
363 HTTP header: "HTTP_CONNECTION".
364 "content_encoding"
366 HTTP header: "HTTP_CONTENT_ENCODING".
367 "content_length"
369 HTTP header: "HTTP_CONTENT_LENGTH".
370 "content_type"
372 HTTP header: "HTTP_CONTENT_TYPE".
373 "forwarded_for_address"
375 HTTP header: "HTTP_X_FORWARDED_FOR".
376 "forwarded_host"
378 HTTP header: "HTTP_X_FORWARDED_HOST".
379 "forwarded_protocol"
381 One of either "HTTP_X_FORWARDED_PROTOCOL",
382 "HTTP_X_FORWARDED_PROTO", or "HTTP_FORWARDED_PROTO".
383 "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 If you have not configured that you are behind a proxy, it returns
390 HTTP header "HTTP_HOST".
391 "keep_alive"
393 HTTP header: "HTTP_KEEP_ALIVE".
394 "referer"
396 HTTP header: "HTTP_REFERER".
397 "user_agent"
399 HTTP header: "HTTP_USER_AGENT".
400 "x_requested_with"
402 HTTP header: "HTTP_X_REQUESTED_WITH".
403
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 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 If you want to see only params from a given source, you can say so by
413 passing the $source param to "params()":
414 my %querystring_params = params('query');
416 my %route_params = params('route');
417 my %post_params = params('body');
418 If source equals "route", then only params parsed from the route
420 pattern are returned.
421 If source equals "query", then only params parsed from the query string
423 are returned.
424 If source equals "body", then only params sent in the request body will
426 be returned.
427 If another value is given for $source, then an exception is triggered.
429
431 If Dancer2::Core::Request detects the following modules as installed,
432 it will use them to speed things up:
433 · URL::Encode::XS
435 · CGI::Deurl::XS
437
439 Dancer Core Developers
440
442 This software is copyright (c) 2020 by Alexis Sukrieh.
443 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.
446perl v5.32.0 2020-07-28 Dancer2::Core::Request(3)