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.301004
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 body_data
46 Returns the body of the request in data form, making it possible to
47 distinguish between "body_parameters", a representation of the request
48 parameters (Hash::MultiValue) and other forms of content.
49 If a serializer is set, this is the deserialized request body.
51 Otherwise this is the decoded body parameters (if any), or the body
52 content itself.
53 content
55 Returns the undecoded byte string POST body.
56 cookies
58 Returns a reference to a hash containing cookies, where the keys are
59 the names of the cookies and values are Dancer2::Core::Cookie objects.
60 data
62 If the application has a serializer and if the request has serialized
63 content, returns the deserialized structure as a hashref.
64 dispatch_path
66 Alias for path. Deprecated.
67 env
69 Return the current PSGI environment hash reference.
70 header($name)
72 Return the value of the given header, if present. If the header has
73 multiple values, returns an the list of values if called in list
74 context, the first one in scalar.
75 headers
77 Returns either an HTTP::Headers or an HTTP::Headers::Fast object
78 representing the headers.
79 id
81 The ID of the request. This allows you to trace a specific request in
82 loggers, per the string created using "to_string".
83 The ID of the request is essentially the number of requests run in the
85 current class.
86 input
88 Alias to "input_handle" method below.
89 input_handle
91 Alias to the PSGI input handle ("<request->env->{psgi.input}>")
92 is_ajax
94 Return true if the value of the header "X-Requested-With" is
95 "XMLHttpRequest".
96 is_delete
98 Return true if the method requested by the client is 'DELETE'
99 is_get
101 Return true if the method requested by the client is 'GET'
102 is_head
104 Return true if the method requested by the client is 'HEAD'
105 is_post
107 Return true if the method requested by the client is 'POST'
108 is_put
110 Return true if the method requested by the client is 'PUT'
111 is_options
113 Return true if the method requested by the client is 'OPTIONS'
114 logger
116 Returns the "psgix.logger" code reference, if exists.
117 method
119 Return the HTTP method used by the client to access the application.
120 While this method returns the method string as provided by the
122 environment, it's better to use one of the following boolean accessors
123 if you want to inspect the requested method.
124 new
126 The constructor of the class, used internally by Dancer2's core to
127 create request objects.
128 It uses the environment hash table given to build the request object:
130 Dancer2::Core::Request->new( env => $env );
132 There are two additional parameters for instantiation:
134 • serializer
136 A serializer object to work with when reading the request body.
138 • body_params
140 Provide body parameters.
142 Used internally when we need to avoid parsing the body again.
144 param($key)
146 Calls the "params" method below and fetches the key provided.
147 params($source)
149 Called in scalar context, returns a hashref of params, either from the
150 specified source (see below for more info on that) or merging all
151 sources.
152 So, you can use, for instance:
154 my $foo = params->{foo}
156 If called in list context, returns a list of key and value pairs, so
158 you could use:
159 my %allparams = params;
161 Parameters are merged in the following order: query, body, route - i.e.
163 route parameters have the highest priority:
164 POST /hello/Ruth?name=Quentin
166 name=Bobbie
168 post '/hello/:name' => sub {
170 return "Hello, " . route_parameters->get('name') . "!"; # returns Ruth
171 return "Hello, " . query_parameters->get('name') . "!"; # returns Quentin
172 return "Hello, " . body_parameters->get('name') . "!"; # returns Bobbie
173 return "Hello, " . param('name') . "!"; # returns Ruth
174 };
175 The "query_parameters", "route_parameters", and "body_parameters"
177 keywords provide a Hash::MultiValue result from the three different
178 parameters. We recommend using these rather than "params", because of
179 the potential for unintentional behaviour - consider the following
180 request and route handler:
181 POST /artist/104/new-song
183 name=Careless Dancing
185 post '/artist/:id/new-song' => sub {
187 find_artist(param('id'))->create_song(params);
188 # oops! we just passed id into create_song,
189 # but we probably only intended to pass name
190 find_artist(param('id'))->create_song(body_parameters);
191 };
192 POST /artist/104/join-band
194 id=4
196 name=Dancing Misfits
197 post '/artist/:id/new-song' => sub {
199 find_artist(param('id'))->join_band(params);
200 # oops! we just passed an id of 104 into join_band,
201 # but we probably should have passed an id of 4
202 };
203 parameters
205 Returns a Hash::MultiValue object with merged GET and POST parameters.
206 Parameters are merged in the following order: query, body, route - i.e.
208 route parameters have the highest priority - see "params" for how this
209 works, and associated risks and alternatives.
210 path
212 The path requested by the client, normalized. This is effectively
213 "path_info" or a single forward "/".
214 path_info
216 The raw requested path. This could be empty. Use "path" instead.
217 port
219 Return the port of the server.
220 protocol
222 Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
223 query_parameters
225 Returns a Hash::MultiValue parameters object.
226 query_string
228 Returns the portion of the request defining the query itself - this is
229 what comes after the "?" in a URI.
230 raw_body
232 Alias to "content" method.
233 remote_address
235 Alias for "address" method.
236 remote_host
238 Return the remote host of the client. This only works with web servers
239 configured to do a reverse DNS lookup on the client's IP address.
240 request_method
242 Alias to the "method" accessor, for backward-compatibility with "CGI"
243 interface.
244 request_uri
246 Return the raw, undecoded request URI path.
247 route
249 Return the route which this request matched.
250 scheme
252 Return the scheme of the request
253 script_name
255 Return script_name from the environment.
256 secure
258 Return true or false, indicating whether the connection is secure -
259 this is effectively checking if the scheme is HTTPS or not.
260 serializer
262 Returns the optional serializer object used to deserialize request
263 parameters.
264 session
266 Returns the "psgix.session" hash, if exists.
267 session_options
269 Returns the "psgix.session.options" hash, if exists.
270 to_string
272 Return a string representing the request object (e.g., "GET
273 /some/path").
274 upload($name)
276 Context-aware accessor for uploads. It's a wrapper around an access to
277 the hash table provided by "uploads()". It looks at the calling context
278 and returns a corresponding value.
279 If you have many file uploads under the same name, and call
281 "upload('name')" in an array context, the accessor will unroll the
282 ARRAY ref for you:
283 my @uploads = request->upload('many_uploads'); # OK
285 Whereas with a manual access to the hash table, you'll end up with one
287 element in @uploads, being the arrayref:
288 my @uploads = request->uploads->{'many_uploads'};
290 # $uploads[0]: ARRAY(0xXXXXX)
291 That is why this accessor should be used instead of a manual access to
293 "uploads".
294 uploads
296 Returns a reference to a hash containing uploads. Values can be either
297 a Dancer2::Core::Request::Upload object, or an arrayref of
298 Dancer2::Core::Request::Upload objects.
299 You should probably use the "upload($name)" accessor instead of
301 manually accessing the "uploads" hash table.
302 uri
304 An alias to "request_uri".
305 uri_base
307 Same thing as "base" above, except it removes the last trailing slash
308 in the path if it is the only path.
309 This means that if your base is http://myserver/, "uri_base" will
311 return http://myserver (notice no trailing slash). This is considered
312 very useful when using templates to do the following thing:
313 <link rel="stylesheet" href="[% request.uri_base %]/css/style.css" />
315 uri_for(path, params)
317 Constructs a URI from the base and the passed path. If params (hashref)
318 is supplied, these are added to the query string of the URI.
319 Thus, with the following base:
321 http://localhost:5000/foo
323 You get the following behavior:
325 my $uri = request->uri_for('/bar', { baz => 'baz' });
327 print $uri; # http://localhost:5000/foo/bar?baz=baz
328 "uri_for" returns a URI object (which can stringify to the value).
330 user
332 Return remote user if defined.
333 var
335 By-name interface to variables stored in this request object.
336 my $stored = $request->var('some_variable');
338 returns the value of 'some_variable', while
340 $request->var('some_variable' => 'value');
342 will set it.
344 vars
346 Access to the internal hash of variables:
347 my $value = $request->vars->{'my_key'};
349 You want to use "var" above.
351
353 Commonly used client-supplied HTTP request headers are available
354 through specific accessors:
355 "accept"
357 HTTP header: "HTTP_ACCEPT".
358 "accept_charset"
360 HTTP header: "HTTP_ACCEPT_CHARSET".
361 "accept_encoding"
363 HTTP header: "HTTP_ACCEPT_ENCODING".
364 "accept_language"
366 HTTP header: "HTTP_ACCEPT_LANGUAGE".
367 "agent"
369 Alias for "user_agent") below.
370 "connection"
372 HTTP header: "HTTP_CONNECTION".
373 "content_encoding"
375 HTTP header: "HTTP_CONTENT_ENCODING".
376 "content_length"
378 HTTP header: "HTTP_CONTENT_LENGTH".
379 "content_type"
381 HTTP header: "HTTP_CONTENT_TYPE".
382 "forwarded_for_address"
384 HTTP header: "HTTP_X_FORWARDED_FOR".
385 "forwarded_host"
387 HTTP header: "HTTP_X_FORWARDED_HOST".
388 "forwarded_protocol"
390 One of either "HTTP_X_FORWARDED_PROTOCOL",
391 "HTTP_X_FORWARDED_PROTO", or "HTTP_FORWARDED_PROTO".
392 "host"
394 Checks whether we are behind a proxy using the "behind_proxy"
395 configuration option, and if so returns the first
396 "HTTP_X_FORWARDED_HOST", since this is a comma separated list.
397 If you have not configured that you are behind a proxy, it returns
399 HTTP header "HTTP_HOST".
400 "keep_alive"
402 HTTP header: "HTTP_KEEP_ALIVE".
403 "referer"
405 HTTP header: "HTTP_REFERER".
406 "user_agent"
408 HTTP header: "HTTP_USER_AGENT".
409 "x_requested_with"
411 HTTP header: "HTTP_X_REQUESTED_WITH".
412
414 If a required source isn't specified, a mixed hashref (or list of key
415 value pairs, in list context) will be returned; this will contain
416 params from all sources (route, query, body).
417 In practical terms, this means that if the param "foo" is passed both
419 on the querystring and in a POST body, you can only access one of them.
420 If you want to see only params from a given source, you can say so by
422 passing the $source param to "params()":
423 my %querystring_params = params('query');
425 my %route_params = params('route');
426 my %post_params = params('body');
427 If source equals "route", then only params parsed from the route
429 pattern are returned.
430 If source equals "query", then only params parsed from the query string
432 are returned.
433 If source equals "body", then only params sent in the request body will
435 be returned.
436 If another value is given for $source, then an exception is triggered.
438
440 If Dancer2::Core::Request detects the following modules as installed,
441 it will use them to speed things up:
442 • URL::Encode::XS
444 • CGI::Deurl::XS
446
448 Dancer Core Developers
449
451 This software is copyright (c) 2021 by Alexis Sukrieh.
452 This is free software; you can redistribute it and/or modify it under
454 the same terms as the Perl 5 programming language system itself.
455perl v5.34.0 2022-01-21 Dancer2::Core::Request(3)