.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Dancer2::Core::Request 3pm"
.TH Dancer2::Core::Request 3pm "2023-12-15" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Dancer2::Core::Request \- Interface for accessing incoming requests
.SH "VERSION"
.IX Header "VERSION"
version 1.1.0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
In a route handler, the current request object can be accessed by the
\&\f(CW\*(C`request\*(C'\fR keyword:
.PP
.Vb 6
\&    get \*(Aq/foo\*(Aq => 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
\&        # ...
\&    };
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
An object representing a Dancer2 request. It aims to provide a proper
interface to anything you might need from a web request.
.SH "METHODS"
.IX Header "METHODS"
.SS "address"
.IX Subsection "address"
Return the \s-1IP\s0 address of the client.
.SS "base"
.IX Subsection "base"
Returns an absolute \s-1URI\s0 for the base of the application.  Returns a \s-1URI\s0
object (which stringifies to the \s-1URL,\s0 as you'd expect).
.SS "body_parameters"
.IX Subsection "body_parameters"
Returns a Hash::MultiValue object representing the \s-1POST\s0 parameters.
.SS "body"
.IX Subsection "body"
Return the raw body of the request, unparsed.
.PP
If you need to access the body of the request, you have to use this accessor and
should not try to read \f(CW\*(C`psgi.input\*(C'\fR by hand. \f(CW\*(C`Dancer2::Core::Request\*(C'\fR
already did it for you and kept the raw body untouched in there.
.SS "body_data"
.IX Subsection "body_data"
Returns the body of the request in data form, making it possible to distinguish
between \f(CW\*(C`body_parameters\*(C'\fR, a representation of the request parameters
(Hash::MultiValue) and other forms of content.
.PP
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.
.SS "content"
.IX Subsection "content"
Returns the undecoded byte string \s-1POST\s0 body.
.SS "cookies"
.IX Subsection "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.
.SS "data"
.IX Subsection "data"
If the application has a serializer and if the request has serialized
content, returns the deserialized structure as a hashref.
.SS "dispatch_path"
.IX Subsection "dispatch_path"
Alias for path. Deprecated.
.SS "env"
.IX Subsection "env"
Return the current \s-1PSGI\s0 environment hash reference.
.SS "header($name)"
.IX Subsection "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.
.SS "headers"
.IX Subsection "headers"
Returns either an HTTP::Headers or an HTTP::Headers::Fast object
representing the headers.
.SS "id"
.IX Subsection "id"
The \s-1ID\s0 of the request. This allows you to trace a specific request in loggers,
per the string created using \f(CW\*(C`to_string\*(C'\fR.
.PP
The \s-1ID\s0 of the request is essentially the number of requests run in the current
class.
.SS "input"
.IX Subsection "input"
Alias to \f(CW\*(C`input_handle\*(C'\fR method below.
.SS "input_handle"
.IX Subsection "input_handle"
Alias to the \s-1PSGI\s0 input handle (\f(CW\*(C`request\->env\->{\*(Aqpsgi.input\*(Aq}\*(C'\fR)
.SS "is_ajax"
.IX Subsection "is_ajax"
Return true if the value of the header \f(CW\*(C`X\-Requested\-With\*(C'\fR is
\&\f(CW\*(C`XMLHttpRequest\*(C'\fR.
.SS "is_delete"
.IX Subsection "is_delete"
Return true if the method requested by the client is '\s-1DELETE\s0'
.SS "is_get"
.IX Subsection "is_get"
Return true if the method requested by the client is '\s-1GET\s0'
.SS "is_head"
.IX Subsection "is_head"
Return true if the method requested by the client is '\s-1HEAD\s0'
.SS "is_post"
.IX Subsection "is_post"
Return true if the method requested by the client is '\s-1POST\s0'
.SS "is_put"
.IX Subsection "is_put"
Return true if the method requested by the client is '\s-1PUT\s0'
.SS "is_options"
.IX Subsection "is_options"
Return true if the method requested by the client is '\s-1OPTIONS\s0'
.SS "logger"
.IX Subsection "logger"
Returns the \f(CW\*(C`psgix.logger\*(C'\fR code reference, if exists.
.SS "method"
.IX Subsection "method"
Return the \s-1HTTP\s0 method used by the client to access the application.
.PP
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.
.SS "new"
.IX Subsection "new"
The constructor of the class, used internally by Dancer2's core to create request
objects.
.PP
It uses the environment hash table given to build the request object:
.PP
.Vb 1
\&    Dancer2::Core::Request\->new( env => $env );
.Ve
.PP
There are two additional parameters for instantiation:
.IP "\(bu" 4
serializer
.Sp
A serializer object to work with when reading the request body.
.IP "\(bu" 4
body_params
.Sp
Provide body parameters.
.Sp
Used internally when we need to avoid parsing the body again.
.SS "param($key)"
.IX Subsection "param($key)"
Calls the \f(CW\*(C`params\*(C'\fR method below and fetches the key provided.
.SS "params($source)"
.IX Subsection "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.
.PP
So, you can use, for instance:
.PP
.Vb 1
\&    my $foo = params\->{foo}
.Ve
.PP
If called in list context, returns a list of key and value pairs, so you could use:
.PP
.Vb 1
\&    my %allparams = params;
.Ve
.PP
Parameters are merged in the following order: query, body, route \- i.e. route
parameters have the highest priority:
.PP
.Vb 1
\&    POST /hello/Ruth?name=Quentin
\&
\&    name=Bobbie
\&
\&    post \*(Aq/hello/:name\*(Aq => sub {
\&        return "Hello, " . route_parameters\->get(\*(Aqname\*(Aq) . "!"; # returns Ruth
\&        return "Hello, " . query_parameters\->get(\*(Aqname\*(Aq) . "!"; # returns Quentin
\&        return "Hello, " . body_parameters\->get(\*(Aqname\*(Aq) . "!";  # returns Bobbie
\&        return "Hello, " . param(\*(Aqname\*(Aq) . "!";                 # returns Ruth
\&    };
.Ve
.PP
The \*(L"query_parameters\*(R", \*(L"route_parameters\*(R", and \*(L"body_parameters\*(R" keywords
provide a Hash::MultiValue result from the three different parameters.
We recommend using these rather than \f(CW\*(C`params\*(C'\fR, because of the potential for
unintentional behaviour \- consider the following request and route handler:
.PP
.Vb 1
\&    POST /artist/104/new\-song
\&
\&    name=Careless Dancing
\&
\&    post \*(Aq/artist/:id/new\-song\*(Aq => sub {
\&      find_artist(param(\*(Aqid\*(Aq))\->create_song(params);
\&      # oops! we just passed id into create_song,
\&      # but we probably only intended to pass name
\&      find_artist(param(\*(Aqid\*(Aq))\->create_song(body_parameters);
\&    };
\&
\&    POST /artist/104/join\-band
\&
\&    id=4
\&    name=Dancing Misfits
\&
\&    post \*(Aq/artist/:id/new\-song\*(Aq => sub {
\&      find_artist(param(\*(Aqid\*(Aq))\->join_band(params);
\&      # oops! we just passed an id of 104 into join_band,
\&      # but we probably should have passed an id of 4
\&    };
.Ve
.SS "parameters"
.IX Subsection "parameters"
Returns a Hash::MultiValue object with merged \s-1GET\s0 and \s-1POST\s0 parameters.
.PP
Parameters are merged in the following order: query, body, route \- i.e. route
parameters have the highest priority \- see \*(L"params\*(R" for how this works, and
associated risks and alternatives.
.SS "path"
.IX Subsection "path"
The path requested by the client, normalized. This is effectively
\&\f(CW\*(C`path_info\*(C'\fR or a single forward \f(CW\*(C`/\*(C'\fR.
.SS "path_info"
.IX Subsection "path_info"
The raw requested path. This could be empty. Use \f(CW\*(C`path\*(C'\fR instead.
.SS "port"
.IX Subsection "port"
Return the port of the server.
.SS "protocol"
.IX Subsection "protocol"
Return the protocol (\fI\s-1HTTP/1.0\s0\fR or \fI\s-1HTTP/1.1\s0\fR) used for the request.
.SS "query_parameters"
.IX Subsection "query_parameters"
Returns a Hash::MultiValue parameters object.
.SS "query_string"
.IX Subsection "query_string"
Returns the portion of the request defining the query itself \- this is
what comes after the \f(CW\*(C`?\*(C'\fR in a \s-1URI.\s0
.SS "raw_body"
.IX Subsection "raw_body"
Alias to \f(CW\*(C`content\*(C'\fR method.
.SS "remote_address"
.IX Subsection "remote_address"
Alias for \f(CW\*(C`address\*(C'\fR method.
.SS "remote_host"
.IX Subsection "remote_host"
Return the remote host of the client. This only works with web servers configured
to do a reverse \s-1DNS\s0 lookup on the client's \s-1IP\s0 address.
.SS "request_method"
.IX Subsection "request_method"
Alias to the \f(CW\*(C`method\*(C'\fR accessor, for backward-compatibility with \f(CW\*(C`CGI\*(C'\fR interface.
.SS "request_uri"
.IX Subsection "request_uri"
Return the raw, undecoded request \s-1URI\s0 path.
.SS "route"
.IX Subsection "route"
Return the route which this request matched.
.SS "scheme"
.IX Subsection "scheme"
Return the scheme of the request
.SS "script_name"
.IX Subsection "script_name"
Return script_name from the environment.
.SS "secure"
.IX Subsection "secure"
Return true or false, indicating whether the connection is secure \- this is
effectively checking if the scheme is \fI\s-1HTTPS\s0\fR or not.
.SS "serializer"
.IX Subsection "serializer"
Returns the optional serializer object used to deserialize request parameters.
.SS "session"
.IX Subsection "session"
Returns the \f(CW\*(C`psgix.session\*(C'\fR hash, if exists.
.SS "session_options"
.IX Subsection "session_options"
Returns the \f(CW\*(C`psgix.session.options\*(C'\fR hash, if exists.
.SS "to_string"
.IX Subsection "to_string"
Return a string representing the request object (e.g., \f(CW\*(C`GET /some/path\*(C'\fR).
.SS "upload($name)"
.IX Subsection "upload($name)"
Context-aware accessor for uploads. It's a wrapper around an access to the hash
table provided by \f(CW\*(C`uploads()\*(C'\fR. It looks at the calling context and returns a
corresponding value.
.PP
If you have many file uploads under the same name, and call \f(CW\*(C`upload(\*(Aqname\*(Aq)\*(C'\fR in
an array context, the accessor will unroll the \s-1ARRAY\s0 ref for you:
.PP
.Vb 1
\&    my @uploads = request\->upload(\*(Aqmany_uploads\*(Aq); # OK
.Ve
.PP
Whereas with a manual access to the hash table, you'll end up with one element
in \f(CW@uploads\fR, being the arrayref:
.PP
.Vb 2
\&    my @uploads = request\->uploads\->{\*(Aqmany_uploads\*(Aq};
\&    # $uploads[0]: ARRAY(0xXXXXX)
.Ve
.PP
That is why this accessor should be used instead of a manual access to
\&\f(CW\*(C`uploads\*(C'\fR.
.SS "uploads"
.IX Subsection "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.
.PP
You should probably use the \f(CW\*(C`upload($name)\*(C'\fR accessor instead of manually accessing the
\&\f(CW\*(C`uploads\*(C'\fR hash table.
.SS "uri"
.IX Subsection "uri"
An alias to \f(CW\*(C`request_uri\*(C'\fR.
.SS "uri_base"
.IX Subsection "uri_base"
Same thing as \f(CW\*(C`base\*(C'\fR above, except it removes the last trailing slash in the
path if it is the only path.
.PP
This means that if your base is \fIhttp://myserver/\fR, \f(CW\*(C`uri_base\*(C'\fR will return
\&\fIhttp://myserver\fR (notice no trailing slash). This is considered very useful
when using templates to do the following thing:
.PP
.Vb 1
\&    <link rel="stylesheet" href="[% request.uri_base %]/css/style.css" />
.Ve
.SS "uri_for(path, params)"
.IX Subsection "uri_for(path, params)"
Constructs a \s-1URI\s0 from the base and the passed path. If params (hashref) is
supplied, these are added to the query string of the \s-1URI.\s0
.PP
Thus, with the following base:
.PP
.Vb 1
\&    http://localhost:5000/foo
.Ve
.PP
You get the following behavior:
.PP
.Vb 2
\&    my $uri = request\->uri_for(\*(Aq/bar\*(Aq, { baz => \*(Aqbaz\*(Aq });
\&    print $uri; # http://localhost:5000/foo/bar?baz=baz
.Ve
.PP
\&\f(CW\*(C`uri_for\*(C'\fR returns a \s-1URI\s0 object (which can stringify to the value).
.SS "uri_for_route(route_name, route_params, query_params, escape)"
.IX Subsection "uri_for_route(route_name, route_params, query_params, escape)"
Constructs a \s-1URI\s0 from the base and the path of the specified route name.
.PP
Read more about it in the \f(CW\*(C`Dancer2::Manual::Keywords\*(C'\fR document under
\&\f(CW\*(C`uri_for_route\*(C'\fR.
.SS "user"
.IX Subsection "user"
Return remote user if defined.
.SS "var"
.IX Subsection "var"
By-name interface to variables stored in this request object.
.PP
.Vb 1
\&  my $stored = $request\->var(\*(Aqsome_variable\*(Aq);
.Ve
.PP
returns the value of 'some_variable', while
.PP
.Vb 1
\&  $request\->var(\*(Aqsome_variable\*(Aq => \*(Aqvalue\*(Aq);
.Ve
.PP
will set it.
.SS "vars"
.IX Subsection "vars"
Access to the internal hash of variables:
.PP
.Vb 1
\&    my $value = $request\->vars\->{\*(Aqmy_key\*(Aq};
.Ve
.PP
You want to use \f(CW\*(C`var\*(C'\fR above.
.SH "Common HTTP request headers"
.IX Header "Common HTTP request headers"
Commonly used client-supplied \s-1HTTP\s0 request headers are available through
specific accessors:
.ie n .IP """accept""" 4
.el .IP "\f(CWaccept\fR" 4
.IX Item "accept"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_ACCEPT\*(C'\fR.
.ie n .IP """accept_charset""" 4
.el .IP "\f(CWaccept_charset\fR" 4
.IX Item "accept_charset"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_ACCEPT_CHARSET\*(C'\fR.
.ie n .IP """accept_encoding""" 4
.el .IP "\f(CWaccept_encoding\fR" 4
.IX Item "accept_encoding"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_ACCEPT_ENCODING\*(C'\fR.
.ie n .IP """accept_language""" 4
.el .IP "\f(CWaccept_language\fR" 4
.IX Item "accept_language"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_ACCEPT_LANGUAGE\*(C'\fR.
.ie n .IP """agent""" 4
.el .IP "\f(CWagent\fR" 4
.IX Item "agent"
Alias for \f(CW\*(C`user_agent\*(C'\fR) below.
.ie n .IP """connection""" 4
.el .IP "\f(CWconnection\fR" 4
.IX Item "connection"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_CONNECTION\*(C'\fR.
.ie n .IP """content_encoding""" 4
.el .IP "\f(CWcontent_encoding\fR" 4
.IX Item "content_encoding"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_CONTENT_ENCODING\*(C'\fR.
.ie n .IP """content_length""" 4
.el .IP "\f(CWcontent_length\fR" 4
.IX Item "content_length"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_CONTENT_LENGTH\*(C'\fR.
.ie n .IP """content_type""" 4
.el .IP "\f(CWcontent_type\fR" 4
.IX Item "content_type"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_CONTENT_TYPE\*(C'\fR.
.ie n .IP """forwarded_for_address""" 4
.el .IP "\f(CWforwarded_for_address\fR" 4
.IX Item "forwarded_for_address"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_X_FORWARDED_FOR\*(C'\fR.
.ie n .IP """forwarded_host""" 4
.el .IP "\f(CWforwarded_host\fR" 4
.IX Item "forwarded_host"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_X_FORWARDED_HOST\*(C'\fR.
.ie n .IP """forwarded_protocol""" 4
.el .IP "\f(CWforwarded_protocol\fR" 4
.IX Item "forwarded_protocol"
One of either \f(CW\*(C`HTTP_X_FORWARDED_PROTOCOL\*(C'\fR, \f(CW\*(C`HTTP_X_FORWARDED_PROTO\*(C'\fR, or
\&\f(CW\*(C`HTTP_FORWARDED_PROTO\*(C'\fR.
.ie n .IP """host""" 4
.el .IP "\f(CWhost\fR" 4
.IX Item "host"
Checks whether we are behind a proxy using the \f(CW\*(C`behind_proxy\*(C'\fR
configuration option, and if so returns the first
\&\f(CW\*(C`HTTP_X_FORWARDED_HOST\*(C'\fR, since this is a comma separated list.
.Sp
If you have not configured that you are behind a proxy, it returns \s-1HTTP\s0
header \f(CW\*(C`HTTP_HOST\*(C'\fR.
.ie n .IP """keep_alive""" 4
.el .IP "\f(CWkeep_alive\fR" 4
.IX Item "keep_alive"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_KEEP_ALIVE\*(C'\fR.
.ie n .IP """referer""" 4
.el .IP "\f(CWreferer\fR" 4
.IX Item "referer"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_REFERER\*(C'\fR.
.ie n .IP """user_agent""" 4
.el .IP "\f(CWuser_agent\fR" 4
.IX Item "user_agent"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_USER_AGENT\*(C'\fR.
.ie n .IP """x_requested_with""" 4
.el .IP "\f(CWx_requested_with\fR" 4
.IX Item "x_requested_with"
\&\s-1HTTP\s0 header: \f(CW\*(C`HTTP_X_REQUESTED_WITH\*(C'\fR.
.SH "Fetching only params from a given source"
.IX Header "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).
.PP
In practical terms, this means that if the param \f(CW\*(C`foo\*(C'\fR is passed both on the
querystring and in a \s-1POST\s0 body, you can only access one of them.
.PP
If you want to see only params from a given source, you can say so by passing
the \f(CW$source\fR param to \f(CW\*(C`params()\*(C'\fR:
.PP
.Vb 3
\&    my %querystring_params = params(\*(Aqquery\*(Aq);
\&    my %route_params       = params(\*(Aqroute\*(Aq);
\&    my %post_params        = params(\*(Aqbody\*(Aq);
.Ve
.PP
If source equals \f(CW\*(C`route\*(C'\fR, then only params parsed from the route pattern
are returned.
.PP
If source equals \f(CW\*(C`query\*(C'\fR, then only params parsed from the query string are
returned.
.PP
If source equals \f(CW\*(C`body\*(C'\fR, then only params sent in the request body will be
returned.
.PP
If another value is given for \f(CW$source\fR, then an exception is triggered.
.SH "EXTRA SPEED"
.IX Header "EXTRA SPEED"
If Dancer2::Core::Request detects the following modules as installed,
it will use them to speed things up:
.IP "\(bu" 4
URL::Encode::XS
.IP "\(bu" 4
CGI::Deurl::XS
.SH "AUTHOR"
.IX Header "AUTHOR"
Dancer Core Developers
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2023 by Alexis Sukrieh.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.