NAME

       Dancer2::Core::Request - Interface for accessing incoming requests

VERSION

       version 0.11

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 environment (%ENV), as a hashref.

   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.

   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.

   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.

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

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

   forward($request, $new_location)
       Create a new request which is a clone of the current one, apart from the path location, which points
       instead to the new location.  This is used internally to chain requests using the forward keyword.

       Note that the new location should be a hash reference. Only one key is required, the "to_url", that
       should point to the URL that forward will use. Optional values are the key "params" to a hash of
       parameters to be added to the current request parameters, and the key "options" that points to a hash of
       options about the redirect (for instance, "method" pointing to a new request method).

   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.

HTTP environment variables

       All HTTP environment variables that are in %ENV will be provided in the Dancer2::Core::Request object
       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"

EXTRA SPEED

       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) 2013 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.