Provided by: libdancer2-perl_0.205002+dfsg-2_all 
NAME
Dancer2::Core::Request - Interface for accessing incoming requests
VERSION
version 0.205002
SYNOPSIS
In a route handler, the current request object can be accessed by the "request" keyword:
get '/foo' => sub {
request->params; # request, params parsed as a hash ref
request->body; # returns the request body, unparsed
request->path; # the path requested by the client
# ...
};
DESCRIPTION
An object representing a Dancer2 request. It aims to provide a proper interface to
anything you might need from a web request.
METHODS
address
Return the IP address of the client.
base
Returns an absolute URI for the base of the application. Returns a URI object (which
stringifies to the URL, as you'd expect).
body_parameters
Returns a Hash::MultiValue object representing the POST parameters.
body
Return the raw body of the request, unparsed.
If you need to access the body of the request, you have to use this accessor and should
not try to read "psgi.input" by hand. "Dancer2::Core::Request" already did it for you and
kept the raw body untouched in there.
content
Returns the undecoded byte string POST body.
cookies
Returns a reference to a hash containing cookies, where the keys are the names of the
cookies and values are Dancer2::Core::Cookie objects.
data
If the application has a serializer and if the request has serialized content, returns the
deserialized structure as a hashref.
dispatch_path
Alias for path. Deprecated.
env
Return the current PSGI environment hash reference.
header($name)
Return the value of the given header, if present. If the header has multiple values,
returns an the list of values if called in list context, the first one in scalar.
headers
Returns either an HTTP::Headers or an HTTP::Headers::Fast object representing the headers.
id
The ID of the request. This allows you to trace a specific request in loggers, per the
string created using "to_string".
The ID of the request is essentially the number of requests run in the current class.
input
Alias to "input_handle" method below.
input_handle
Alias to the PSGI input handle ("<request->env->{psgi.input}>")
is_ajax
Return true if the value of the header "X-Requested-With" is "XMLHttpRequest".
is_delete
Return true if the method requested by the client is 'DELETE'
is_get
Return true if the method requested by the client is 'GET'
is_head
Return true if the method requested by the client is 'HEAD'
is_post
Return true if the method requested by the client is 'POST'
is_put
Return true if the method requested by the client is 'PUT'
is_options
Return true if the method requested by the client is 'OPTIONS'
logger
Returns the "psgix.logger" code reference, if exists.
method
Return the HTTP method used by the client to access the application.
While this method returns the method string as provided by the environment, it's better to
use one of the following boolean accessors if you want to inspect the requested method.
new
The constructor of the class, used internally by Dancer2's core to create request objects.
It uses the environment hash table given to build the request object:
Dancer2::Core::Request->new( env => $env );
There are two additional parameters for instantiation:
• serializer
A serializer object to work with when reading the request body.
• body_params
Provide body parameters.
Used internally when we need to avoid parsing the body again.
param($key)
Calls the "params" method below and fetches the key provided.
params($source)
Called in scalar context, returns a hashref of params, either from the specified source
(see below for more info on that) or merging all sources.
So, you can use, for instance:
my $foo = params->{foo}
If called in list context, returns a list of key and value pairs, so you could use:
my %allparams = params;
Parameters are merged in the following order: query, body, route - i.e. route parameters
have the highest priority:
POST /hello/Ruth?name=Quentin
name=Bobbie
post '/hello/:name' => sub {
return "Hello, " . route_parameters->get('name') . "!"; # returns Ruth
return "Hello, " . query_parameters->get('name') . "!"; # returns Quentin
return "Hello, " . body_parameters->get('name') . "!"; # returns Bobbie
return "Hello, " . param('name') . "!"; # returns Ruth
};
The "query_parameters", "route_parameters", and "body_parameters" keywords provide a
Hash::MultiValue result from the three different parameters. We recommend using these
rather than "params", because of the potential for unintentional behaviour - consider the
following request and route handler:
POST /artist/104/new-song
name=Careless Dancing
post '/artist/:id/new-song' => sub {
find_artist(param('id'))->create_song(params);
# oops! we just passed id into create_song,
# but we probably only intended to pass name
find_artist(param('id'))->create_song(body_parameters);
};
POST /artist/104/join-band
id=4
name=Dancing Misfits
post '/artist/:id/new-song' => sub {
find_artist(param('id'))->join_band(params);
# oops! we just passed an id of 104 into join_band,
# but we probably should have passed an id of 4
};
parameters
Returns a Hash::MultiValue object with merged GET and POST parameters.
Parameters are merged in the following order: query, body, route - i.e. route parameters
have the highest priority - see "params" for how this works, and associated risks and
alternatives.
path
The path requested by the client, normalized. This is effectively "path_info" or a single
forward "/".
path_info
The raw requested path. This could be empty. Use "path" instead.
port
Return the port of the server.
protocol
Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
query_parameters
Returns a Hash::MultiValue parameters object.
query_string
Returns the portion of the request defining the query itself - this is what comes after
the "?" in a URI.
raw_body
Alias to "content" method.
remote_address
Alias for "address" method.
remote_host
Return the remote host of the client. This only works with web servers configured to do a
reverse DNS lookup on the client's IP address.
request_method
Alias to the "method" accessor, for backward-compatibility with "CGI" interface.
request_uri
Return the raw, undecoded request URI path.
route
Return the route which this request matched.
scheme
Return the scheme of the request
script_name
Return script_name from the environment.
secure
Return true or false, indicating whether the connection is secure - this is effectively
checking if the scheme is HTTPS or not.
serializer
Returns the optional serializer object used to deserialize request parameters.
session
Returns the "psgix.session" hash, if exists.
session_options
Returns the "psgix.session.options" hash, if exists.
to_string
Return a string representing the request object (e.g., "GET /some/path").
upload($name)
Context-aware accessor for uploads. It's a wrapper around an access to the hash table
provided by "uploads()". It looks at the calling context and returns a corresponding
value.
If you have many file uploads under the same name, and call "upload('name')" in an array
context, the accessor will unroll the ARRAY ref for you:
my @uploads = request->upload('many_uploads'); # OK
Whereas with a manual access to the hash table, you'll end up with one element in
@uploads, being the arrayref:
my @uploads = request->uploads->{'many_uploads'};
# $uploads[0]: ARRAY(0xXXXXX)
That is why this accessor should be used instead of a manual access to "uploads".
uploads
Returns a reference to a hash containing uploads. Values can be either a
Dancer2::Core::Request::Upload object, or an arrayref of Dancer2::Core::Request::Upload
objects.
You should probably use the "upload($name)" accessor instead of manually accessing the
"uploads" hash table.
uri
An alias to "request_uri".
uri_base
Same thing as "base" above, except it removes the last trailing slash in the path if it is
the only path.
This means that if your base is http://myserver/, "uri_base" will return http://myserver
(notice no trailing slash). This is considered very useful when using templates to do the
following thing:
<link rel="stylesheet" href="[% request.uri_base %]/css/style.css" />
uri_for(path, params)
Constructs a URI from the base and the passed path. If params (hashref) is supplied, these
are added to the query string of the URI.
Thus, with the following base:
http://localhost:5000/foo
You get the following behavior:
my $uri = request->uri_for('/bar', { baz => 'baz' });
print $uri; # http://localhost:5000/foo/bar?baz=baz
"uri_for" returns a URI object (which can stringify to the value).
user
Return remote user if defined.
var
By-name interface to variables stored in this request object.
my $stored = $request->var('some_variable');
returns the value of 'some_variable', while
$request->var('some_variable' => 'value');
will set it.
vars
Access to the internal hash of variables:
my $value = $request->vars->{'my_key'};
You want to use "var" above.
Common HTTP request headers
Commonly used client-supplied HTTP request headers are available through specific
accessors:
"accept"
HTTP header: "HTTP_ACCEPT".
"accept_charset"
HTTP header: "HTTP_ACCEPT_CHARSET".
"accept_encoding"
HTTP header: "HTTP_ACCEPT_ENCODING".
"accept_language"
HTTP header: "HTTP_ACCEPT_LANGUAGE".
"agent"
Alias for "user_agent") below.
"connection"
HTTP header: "HTTP_CONNECTION".
"content_encoding"
HTTP header: "HTTP_CONTENT_ENCODING".
"content_length"
HTTP header: "HTTP_CONTENT_LENGTH".
"content_type"
HTTP header: "HTTP_CONTENT_TYPE".
"forwarded_for_address"
HTTP header: "HTTP_X_FORWARDED_FOR".
"forwarded_host"
HTTP header: "HTTP_X_FORWARDED_HOST".
"forwarded_protocol"
One of either "HTTP_X_FORWARDED_PROTOCOL", "HTTP_X_FORWARDED_PROTO", or
"HTTP_FORWARDED_PROTO".
"host"
Checks whether we are behind a proxy using the "behind_proxy" configuration option,
and if so returns the first "HTTP_X_FORWARDED_HOST", since this is a comma separated
list.
If you have not configured that you are behind a proxy, it returns HTTP header
"HTTP_HOST".
"keep_alive"
HTTP header: "HTTP_KEEP_ALIVE".
"referer"
HTTP header: "HTTP_REFERER".
"user_agent"
HTTP header: "HTTP_USER_AGENT".
"x_requested_with"
HTTP header: "HTTP_X_REQUESTED_WITH".
Fetching only params from a given source
If a required source isn't specified, a mixed hashref (or list of key value pairs, in list
context) will be returned; this will contain params from all sources (route, query, body).
In practical terms, this means that if the param "foo" is passed both on the querystring
and in a POST body, you can only access one of them.
If you want to see only params from a given source, you can say so by passing the $source
param to "params()":
my %querystring_params = params('query');
my %route_params = params('route');
my %post_params = params('body');
If source equals "route", then only params parsed from the route pattern are returned.
If source equals "query", then only params parsed from the query string are returned.
If source equals "body", then only params sent in the request body will be returned.
If another value is given for $source, then an exception is triggered.
EXTRA SPEED
If Dancer2::Core::Request detects the following modules as installed, it will use them to
speed things up:
• URL::Encode::XS
• CGI::Deurl::XS
AUTHOR
Dancer Core Developers
COPYRIGHT AND LICENSE
This software is copyright (c) 2017 by Alexis Sukrieh.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.