NAME¶
Dancer2::Core::Request - Interface for accessing incoming requests
VERSION¶
version 0.152000
SYNOPSIS¶
In a route handler, the current request object can be accessed by the
"request" method, like in the following example:
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
# ...
};
A route handler should not read the environment by itself, but should instead
use the current request object.
DESCRIPTION¶
This class implements a common interface for accessing incoming requests in a
Dancer2 application.
METHODS¶
env()¶
Return the current PSGI environment hash reference.
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.
path()¶
Return the path requested by the client.
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.
content_type()¶
Return the content type of the request.
content_length()¶
Return the content length of the request.
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.
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.
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.
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);
It also accepts the "body_is_parsed" boolean flag, if the new request
object should not parse request body.
address()¶
Return the IP address of the client.
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.
protocol()¶
Return the protocol (HTTP/1.0 or HTTP/1.1) used for the request.
port()¶
Return the port of the server.
request_uri()¶
Return the raw, undecoded request URI path.
user()¶
Return remote user if defined.
script_name()¶
Return script_name from the environment.
scheme()¶
Return the scheme of the request
serializer()¶
Returns the optional serializer object used to deserialize request parameters.
data()¶
If the application has a serializer and if the request has serialized content,
returns the deserialized structure as a hashref.
secure()¶
Return true of false, indicating whether the connection is secure
uri()¶
An alias to
request_uri()
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_delete()¶
Return true if the method requested by the client is 'DELETE'
request_method¶
Alias to the "method" accessor, for backward-compatibility with
"CGI" interface.
Alias to the PSGI input handle
("<request->env->{psgi.input}>")
to_string()¶
Return a string representing the request object (eg: "GET /some/path")
base()¶
Returns an absolute URI for the base of the application. Returns a URI object
(which stringifies to the URL, as you'd expect).
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" />
dispatch_path()¶
The part of the "path" after "base". This is the path used
for dispatching the request to routes.
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. If the base is
"
http://localhost:5000/foo", "request->uri_for('/bar', { baz
=> 'baz' })" would return
"
http://localhost:5000/foo/bar?baz=baz". Returns a URI object (which
stringifies to the URL, as you'd expect).
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 => value pairs, so you could
use:
my %allparams = params;
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.
is_ajax()¶
Return true if the value of the header "X-Requested-With" is
XMLHttpRequest.
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 ARRAY ref:
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".
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.
Commonly used client-supplied HTTP request headers are available through
specific accessors, here are those supported:
- "accept"
- "accept_charset"
- "accept_encoding"
- "accept_language"
- "accept_type"
- "agent" (alias for "user_agent")
- "connection"
- "forwarded_for_address"
- "forwarded_protocol"
- "forwarded_host"
- "host"
- "keep_alive"
- "path_info"
- "referer"
- "remote_address"
- "user_agent"
- "x_requested_with"
With the exception of "host", these accessors are lookups into the
PSGI env hash reference.
Note that the PSGI specification prefixes client-supplied request headers with
"HTTP_". For example, a "X-Requested-With" header has the
key "HTTP_X_REQUESTED_WITH" in the PSGI env hashref.
Install URL::Encode::XS and CGI::Deurl::XS for extra speed.
Dancer2::Core::Request will use it if they detect their presence.
SEE ALSO¶
Dancer2
AUTHOR¶
Dancer Core Developers
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2014 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.