Dancer2::Core::Request - Interface for accessing incoming requests
version 1.1.2
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
# ...
};An object representing a Dancer2 request. It aims to provide a proper interface to anything you might need from a web request.
Return the IP address of the client.
Returns an absolute URI for the base of the application. Returns a URI object (which stringifies to the URL, as you'd expect).
Returns a Hash::MultiValue object representing the POST parameters.
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.
Returns the body of the request in data form, making it possible to distinguish between body_parameters, a representation of the request parameters (Hash::MultiValue) and other forms of content.
If a serializer is set, this is the deserialized request body. Otherwise this is the decoded body parameters (if any), or the body content itself.
Returns the undecoded byte string POST body.
Returns a reference to a hash containing cookies, where the keys are the names of the cookies and values are Dancer2::Core::Cookie objects.
If the application has a serializer and if the request has serialized content, returns the deserialized structure as a hashref.
Alias for path. Deprecated.
Return the current PSGI environment hash reference.
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.
Returns either an HTTP::Headers or an HTTP::Headers::Fast object representing the headers.
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.
Alias to input_handle method below.
Alias to the PSGI input handle (request->env->{'psgi.input'})
Return true if the value of the header X-Requested-With is XMLHttpRequest.
Return true if the method requested by the client is 'DELETE'
Return true if the method requested by the client is 'GET'
Return true if the method requested by the client is 'HEAD'
Return true if the method requested by the client is 'POST'
Return true if the method requested by the client is 'PUT'
Return true if the method requested by the client is 'OPTIONS'
Returns the psgix.logger code reference, if exists.
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.
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.
Calls the params method below and fetches the key provided.
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
};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.
The path requested by the client, normalized. This is effectively path_info or a single forward /.
The raw requested path. This could be empty. Use path instead.
Return the port of the server.
Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
Returns a Hash::MultiValue parameters object.
Returns the portion of the request defining the query itself - this is what comes after the ? in a URI.
Alias to content method.
Alias for address method.
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.
Alias to the method accessor, for backward-compatibility with CGI interface.
Return the raw, undecoded request URI path.
Return the route which this request matched.
Return the scheme of the request
Return script_name from the environment.
Return true or false, indicating whether the connection is secure - this is effectively checking if the scheme is HTTPS or not.
Returns the optional serializer object used to deserialize request parameters.
Returns the psgix.session hash, if exists.
Returns the psgix.session.options hash, if exists.
Return a string representing the request object (e.g., GET /some/path).
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'); # OKWhereas 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.
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.
An alias to request_uri.
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" />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/fooYou get the following behavior:
my $uri = request->uri_for('/bar', { baz => 'baz' });
print $uri; # http://localhost:5000/foo/bar?baz=bazuri_for returns a URI object (which can stringify to the value).
Constructs a URI from the base and the path of the specified route name.
Read more about it in the Dancer2::Manual::Keywords document under uri_for_route.
Return remote user if defined.
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.
Access to the internal hash of variables:
my $value = $request->vars->{'my_key'};You want to use var above.
Commonly used client-supplied HTTP request headers are available through specific accessors:
acceptHTTP header: HTTP_ACCEPT.
accept_charsetHTTP header: HTTP_ACCEPT_CHARSET.
accept_encodingHTTP header: HTTP_ACCEPT_ENCODING.
accept_languageHTTP header: HTTP_ACCEPT_LANGUAGE.
agentAlias for user_agent) below.
connectionHTTP header: HTTP_CONNECTION.
content_encodingHTTP header: HTTP_CONTENT_ENCODING.
content_lengthHTTP header: HTTP_CONTENT_LENGTH.
content_typeHTTP header: HTTP_CONTENT_TYPE.
forwarded_for_addressHTTP header: HTTP_X_FORWARDED_FOR.
forwarded_hostHTTP header: HTTP_X_FORWARDED_HOST.
forwarded_protocolOne of either HTTP_X_FORWARDED_PROTOCOL, HTTP_X_FORWARDED_PROTO, or HTTP_FORWARDED_PROTO.
hostChecks 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_aliveHTTP header: HTTP_KEEP_ALIVE.
refererHTTP header: HTTP_REFERER.
user_agentHTTP header: HTTP_USER_AGENT.
x_requested_withHTTP header: HTTP_X_REQUESTED_WITH.
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.
If Dancer2::Core::Request detects the following modules as installed, it will use them to speed things up:
Dancer Core Developers
This software is copyright (c) 2024 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.