/ 
Dancer-1.3000_02
River stage three • 211 direct dependents • 215 total dependents
/ Dancer::Request

NAME

Dancer::Request - interface for accessing incoming requests

DESCRIPTION

This class implements a common interface for accessing incoming requests in a Dancer application.

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.

PUBLIC INTERFACE

new($env)

The constructor of the class, used internally by Dancer's core to create request objects. It uses the environment hash table given to build the request object.

new_for_request($method, $path, $params, $body, $headers)

An alternate constructor convinient for test scripts which creates a request object with the arguments given.

to_string()

Return a string represeting the request object (eg: "GET /some/path")

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.

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'

path()

Return the path requested by the client.

base()

Returns an absolute URI for the base of the application

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.

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.

Vars

Alias to the params accessor, for backward-compatibility with CGI interface.

request_method

Alias to the method accessor, for backward-compatibility with CGI interface.

input_handle

Alias to the PSGI input handle (<request->env->{psgi.input}>)

content_type()

Return the content type of the request.

content_length()

Return the content length of the request.

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.

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. Dancer::Request already did it for you and kept the raw body untouched in there.

is_ajax()

Return true if the value of the header X-Requested-With is XMLHttpRequest.

env()

Return the current environment (%ENV), as a hashref.

uploads()

Returns a reference to a hash containing uploads. Values can be either a Dancer::Request::Upload object, or an arrayref of Dancer::Request::Upload objects.

You should probably use the upload($name) accessor instead of manually accessing the uploads hash table.

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 accesor will unroll the ARRA 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.

HTTP environment variables

All HTTP environment variables that are in %ENV will be provided in the Dancer::Request object through specific accessors, here are those supported:

user_agent
agent (alias for user_agent)
host
accept_language
accept_charset
accept_encoding
keep_alive
connection
accept
forwarded_for_address
remote_address

AUTHORS

This module has been written by Alexis Sukrieh and was mostly inspired by Plack::Request, written by Tatsuiko Miyagawa.

Tatsuiko Miyagawa also gave a hand for the PSGI interface.

LICENCE

This module is released under the same terms as Perl itself.

SEE ALSO

Dancer