Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Dancer2::Core::RequestUser Contributed Perl DocumentaDancer2::Core::Request(3)

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

VERSION
       version 0.300004

SYNOPSIS
       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
	       # ...
	   };

DESCRIPTION
       An object representing a	Dancer2	request. It aims to provide a proper
       interface to anything you might need from a web request.

METHODS
   address
       Return the IP address of	the client.

   base
       Returns an absolute URI for the base of the application.	 Returns a URI
       object (which stringifies to the	URL, as	you'd expect).

   body_parameters
       Returns a Hash::MultiValue object representing the POST parameters.

   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.

   content
       Returns the undecoded byte string POST body.

   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.

   data
       If the application has a	serializer and if the request has serialized
       content,	returns	the deserialized structure as a	hashref.

   dispatch_path
       Alias for path. Deprecated.

   env
       Return the current PSGI environment hash	reference.

   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.

   headers
       Returns either an HTTP::Headers or an HTTP::Headers::Fast object
       representing the	headers.

   id
       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.

   input
       Alias to	"input_handle" method below.

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

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

   is_delete
       Return true if the method requested by the client is 'DELETE'

   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_options
       Return true if the method requested by the client is 'OPTIONS'

   logger
       Returns the "psgix.logger" code reference, if exists.

   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.

   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 );

       There are two additional	parameters for instantiation:

       o   serializer

	   A serializer	object to work with when reading the request body.

       o   body_params

	   Provide body	parameters.

	   Used	internally when	we need	to avoid parsing the body again.

   param($key)
       Calls the "params" method below and fetches the key provided.

   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	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
	   };

   parameters
       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.

   path
       The path	requested by the client, normalized. This is effectively
       "path_info" or a	single forward "/".

   path_info
       The raw requested path. This could be empty. Use	"path" instead.

   port
       Return the port of the server.

   protocol
       Return the protocol (HTTP/1.0 or	HTTP/1.1) used for the request.

   query_parameters
       Returns a Hash::MultiValue parameters object.

   query_string
       Returns the portion of the request defining the query itself - this is
       what comes after	the "?"	in a URI.

   raw_body
       Alias to	"content" method.

   remote_address
       Alias for "address" method.

   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.

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

   request_uri
       Return the raw, undecoded request URI path.

   route
       Return the route	which this request matched.

   scheme
       Return the scheme of the	request

   script_name
       Return script_name from the environment.

   secure
       Return true or false, indicating	whether	the connection is secure -
       this is effectively checking if the scheme is HTTPS or not.

   serializer
       Returns the optional serializer object used to deserialize request
       parameters.

   session
       Returns the "psgix.session" hash, if exists.

   session_options
       Returns the "psgix.session.options" hash, if exists.

   to_string
       Return a	string representing the	request	object (e.g., "GET
       /some/path").

   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 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".

   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.

   uri
       An alias	to "request_uri".

   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" />

   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.

       Thus, with the following	base:

	   http://localhost:5000/foo

       You get the following behavior:

	   my $uri = request->uri_for('/bar', {	baz => 'baz' });
	   print $uri; # http://localhost:5000/foo/bar?baz=baz

       "uri_for" returns a URI object (which can stringify to the value).

   user
       Return remote user if defined.

   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.

   vars
       Access to the internal hash of variables:

	   my $value = $request->vars->{'my_key'};

       You want	to use "var" above.

Common HTTP request headers
       Commonly	used client-supplied HTTP request headers are available
       through specific	accessors:

       "accept"
	   HTTP	header:	"HTTP_ACCEPT".

       "accept_charset"
	   HTTP	header:	"HTTP_ACCEPT_CHARSET".

       "accept_encoding"
	   HTTP	header:	"HTTP_ACCEPT_ENCODING".

       "accept_language"
	   HTTP	header:	"HTTP_ACCEPT_LANGUAGE".

       "agent"
	   Alias for "user_agent") below.

       "connection"
	   HTTP	header:	"HTTP_CONNECTION".

       "content_encoding"
	   HTTP	header:	"HTTP_CONTENT_ENCODING".

       "content_length"
	   HTTP	header:	"HTTP_CONTENT_LENGTH".

       "content_type"
	   HTTP	header:	"HTTP_CONTENT_TYPE".

       "forwarded_for_address"
	   HTTP	header:	"HTTP_X_FORWARDED_FOR".

       "forwarded_host"
	   HTTP	header:	"HTTP_X_FORWARDED_HOST".

       "forwarded_protocol"
	   One of either "HTTP_X_FORWARDED_PROTOCOL",
	   "HTTP_X_FORWARDED_PROTO", or	"HTTP_FORWARDED_PROTO".

       "host"
	   Checks 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_alive"
	   HTTP	header:	"HTTP_KEEP_ALIVE".

       "referer"
	   HTTP	header:	"HTTP_REFERER".

       "user_agent"
	   HTTP	header:	"HTTP_USER_AGENT".

       "x_requested_with"
	   HTTP	header:	"HTTP_X_REQUESTED_WITH".

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.

EXTRA SPEED
       If Dancer2::Core::Request detects the following modules as installed,
       it will use them	to speed things	up:

       o   URL::Encode::XS

       o   CGI::Deurl::XS

AUTHOR
       Dancer Core Developers

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2020 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.

perl v5.32.0			  2020-05-27	     Dancer2::Core::Request(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | Common HTTP request headers | Fetching only params from a given source | EXTRA SPEED | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Dancer2::Core::Request&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help