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

FreeBSD Manual Pages

  
 
  

home | help
Catalyst::Request(3)  User Contributed Perl Documentation Catalyst::Request(3)

NAME
       Catalyst::Request - provides information	about the current client
       request

SYNOPSIS
	   $req	= $c->request;
	   $req->address eq "127.0.0.1";
	   $req->arguments;
	   $req->args;
	   $req->base;
	   $req->body;
	   $req->body_data;
	   $req->body_parameters;
	   $req->content_encoding;
	   $req->content_length;
	   $req->content_type;
	   $req->cookie;
	   $req->cookies;
	   $req->header;
	   $req->headers;
	   $req->hostname;
	   $req->input;
	   $req->query_keywords;
	   $req->match;
	   $req->method;
	   $req->param;
	   $req->parameters;
	   $req->params;
	   $req->path;
	   $req->protocol;
	   $req->query_parameters;
	   $req->read;
	   $req->referer;
	   $req->secure;
	   $req->captures;
	   $req->upload;
	   $req->uploads;
	   $req->uri;
	   $req->user;
	   $req->user_agent;
	   $req->env;

       See also	Catalyst, Catalyst::Request::Upload.

DESCRIPTION
       This is the Catalyst Request class, which provides an interface to data
       for the current client request. The request object is prepared by
       Catalyst::Engine, thus hiding the details of the	particular engine
       implementation.

METHODS
   $req->address
       Returns the IP address of the client.

   $req->arguments
       Returns a reference to an array containing the arguments.

	   print $c->request->arguments->[0];

       For example, if your action was

	   package MyApp::Controller::Foo;

	   sub moose : Local {
	       ...
	   }

       and the URI for the request was "http://.../foo/moose/bah", the string
       "bah" would be the first	and only argument.

       Arguments get automatically URI-unescaped for you.

   $req->args
       Shortcut	for "arguments".

   $req->base
       Contains	the URI	base. This will	always have a trailing slash. Note
       that the	URI scheme (e.g., http vs. https) must be determined through
       heuristics; depending on	your server configuration, it may be
       incorrect. See $req->secure for more info.

       If your application was queried with the	URI
       "http://localhost:3000/some/path" then "base" is
       "http://localhost:3000/".

   $req->body
       Returns the message body	of the request,	as returned by HTTP::Body: a
       string, unless Content-Type is "application/x-www-form-urlencoded",
       "text/xml", or "multipart/form-data", in	which case a File::Temp	object
       is returned.

   $req->body_data
       Returns a Perl representation of	POST/PUT body data that	is not classic
       HTML form data, such as JSON, XML, etc.	By default, Catalyst will
       parse incoming data of the type 'application/json' and return access to
       that data via this method.  You may define addition data_handlers via a
       global configuration setting.  See "Catalyst\DATA HANDLERS" for more
       information.

       If the POST is malformed	in some	way (such as undefined or not content
       that matches the	content-type) we raise a Catalyst::Exception with the
       error text as the message.

       If the POSTed content type does not match an available data handler,
       this will also raise an exception.

   $req->body_parameters
       Returns a reference to a	hash containing	body (POST) parameters.	Values
       can be either a scalar or an arrayref containing	scalars.

	   print $c->request->body_parameters->{field};
	   print $c->request->body_parameters->{field}->[0];

       These are the parameters	from the POST part of the request, if any.

       NOTE If your POST is multipart, but contains non	file upload parts
       (such as	an line	part with an alternative encoding or content type) we
       do our best to try and figure out how the value should be presented.
       If there's a specified character	set we will use	that to	decode rather
       than the	default	encoding set by	the application.  However if there are
       complex headers and we cannot determine the correct way to extra	a
       meaningful value	from the upload, in this case any part like this will
       be represented as an instance of	Catalyst::Request::PartData.

       Patches and review of this part of the code welcomed.

   $req->body_params
       Shortcut	for body_parameters.

   $req->content_encoding
       Shortcut	for $req->headers->content_encoding.

   $req->content_length
       Shortcut	for $req->headers->content_length.

   $req->content_type
       Shortcut	for $req->headers->content_type.

   $req->cookie
       A convenient method to access $req->cookies.

	   $cookie  = $c->request->cookie('name');
	   @cookies = $c->request->cookie;

   $req->cookies
       Returns a reference to a	hash containing	the cookies.

	   print $c->request->cookies->{mycookie}->value;

       The cookies in the hash are indexed by name, and	the values are
       CGI::Simple::Cookie objects.

   $req->header
       Shortcut	for $req->headers->header.

   $req->headers
       Returns an HTTP::Headers	object containing the headers for the current
       request.

	   print $c->request->headers->header('X-Catalyst');

   $req->hostname
       Returns the hostname of the client. Use "$req->uri->host" to get	the
       hostname	of the server.

   $req->input
       Alias for $req->body.

   $req->query_keywords
       Contains	the keywords portion of	a query	string,	when no	'=' signs are
       present.

	   http://localhost/path?some+keywords

	   $c->request->query_keywords will contain 'some keywords'

   $req->match
       This contains the matching part of a Regex action. Otherwise it returns
       the same	as 'action', except for	default	actions, which return an empty
       string.

   $req->method
       Contains	the request method ("GET", "POST", "HEAD", etc).

   $req->param
       Returns GET and POST parameters with a CGI.pm-compatible	param method.
       This is an alternative method for accessing parameters in
       $c->req->parameters.

	   $value  = $c->request->param( 'foo' );
	   @values = $c->request->param( 'foo' );
	   @params = $c->request->param;

       Like CGI, and unlike earlier versions of	Catalyst, passing multiple
       arguments to this method, like this:

	   $c->request->param( 'foo', 'bar', 'gorch', 'quxx' );

       will set	the parameter "foo" to the multiple values "bar", "gorch" and
       "quxx". Previously this would have added	"bar" as another value to
       "foo" (creating it if it	didn't exist before), and "quxx" as another
       value for "gorch".

       NOTE this is considered a legacy	interface and care should be taken
       when using it. "scalar $c->req->param( 'foo' )" will return only	the
       first "foo" param even if multiple are present; "$c->req->param(	'foo'
       )" will return a	list of	as many	are present, which can have unexpected
       consequences when writing code of the form:

	   $foo->bar(
	       a => 'b',
	       baz => $c->req->param( 'baz' ),
	   );

       If multiple "baz" parameters are	provided this code might corrupt data
       or cause	a hash initialization error. For a more	straightforward
       interface see "$c->req->parameters".

       NOTE Interfaces like this, which	are based on CGI and the "param"
       method are known	to cause demonstrated exploits.	It is highly
       recommended that	you avoid using	this method, and migrate existing code
       away from it.  Here's a whitepaper of the exploit:

       <http://blog.gerv.net/2014/10/new-class-of-vulnerability-in-perl-web-applications/>

       NOTE Further discussion on IRC indicate that the	Catalyst core team
       from 'back then'	were well aware	of this	hack and this is the main
       reason we added the new approach	to getting parameters in the first
       place.

       Basically this is an exploit that takes advantage of how	\param will do
       one thing in scalar context and another thing in	list context.  This is
       combined	with how Perl chooses to deal with duplicate keys in a hash
       definition by overwriting the value of existing keys with a new value
       if the same key shows up	again.	Generally you will be vulnerable to
       this exploit if you are using this method in a direct assignment	in a
       hash, such as with a DBIx::Class	create statement.  For example,	if you
       have parameters like:

	   user?user=123&foo=a&foo=user&foo=456

       You could end up	with extra parameters injected into your method	calls:

	   $c->model('User')->create({
	     user => $c->req->param('user'),
	     foo => $c->req->param('foo'),
	   });

       Which would look	like:

	   $c->model('User')->create({
	     user => 123,
	     foo => qw(a user 456),
	   });

       (or to be absolutely clear if you are not seeing	it):

	   $c->model('User')->create({
	     user => 456,
	     foo => 'a',
	   });

       Possible	remediations include scrubbing your parameters with a form
       validator like HTML::FormHandler	or being careful to force scalar
       context using the scalar	keyword:

	   $c->model('User')->create({
	     user => scalar($c->req->param('user')),
	     foo => scalar($c->req->param('foo')),
	   });

       Upcoming	versions of Catalyst will disable this interface by default
       and require you to positively enable it should you require it for
       backwards compatibility reasons.

   $req->parameters
       Returns a reference to a	hash containing	GET and	POST parameters.
       Values can be either a scalar or	an arrayref containing scalars.

	   print $c->request->parameters->{field};
	   print $c->request->parameters->{field}->[0];

       This is the combination of "query_parameters" and "body_parameters".

   $req->params
       Shortcut	for $req->parameters.

   $req->path
       Returns the path, i.e. the part of the URI after	$req->base, for	the
       current request.

	   http://localhost/path/foo

	   $c->request->path will contain 'path/foo'

   $req->path_info
       Alias for path, added for compatibility with CGI.

   $req->protocol
       Returns the protocol (HTTP/1.0 or HTTP/1.1) used	for the	current
       request.

   $req->query_parameters
   $req->query_params
       Returns a reference to a	hash containing	query string (GET) parameters.
       Values can be either a scalar or	an arrayref containing scalars.

	   print $c->request->query_parameters->{field};
	   print $c->request->query_parameters->{field}->[0];

   $req->read( [$maxlength] )
       Reads a chunk of	data from the request body. This method	is intended to
       be used in a while loop,	reading	$maxlength bytes on every call.
       $maxlength defaults to the size of the request if not specified.

   $req->read_chunk(\$buff, $max)
       Reads a chunk.

       You have	to set MyApp->config(parse_on_demand =>	1) to use this
       directly.

   $req->referer
       Shortcut	for $req->headers->referer. Returns the	referring page.

   $req->secure
       Returns true or false, indicating whether the connection	is secure
       (https).	The reliability	of $req->secure	may depend on your server
       configuration; Catalyst relies on PSGI to determine whether or not a
       request is secure (Catalyst looks at psgi.url_scheme), and different
       PSGI servers may	make this determination	in different ways (as by
       directly	passing	along information from the server, interpreting	any of
       several HTTP headers, or	using heuristics of their own).

   $req->captures
       Returns a reference to an array containing captured args	from chained
       actions or regex	captures.

	   my @captures	= @{ $c->request->captures };

   $req->upload
       A convenient method to access $req->uploads.

	   $upload  = $c->request->upload('field');
	   @uploads = $c->request->upload('field');
	   @fields  = $c->request->upload;

	   for my $upload ( $c->request->upload('field') ) {
	       print $upload->filename;
	   }

   $req->uploads
       Returns a reference to a	hash containing	uploads. Values	can be either
       a Catalyst::Request::Upload object, or an arrayref of
       Catalyst::Request::Upload objects.

	   my $upload =	$c->request->uploads->{field};
	   my $upload =	$c->request->uploads->{field}->[0];

   $req->uri
       Returns a URI object for	the current request. Stringifies to the	URI
       text.

   $req->mangle_params(	{ key => 'value' }, $appendmode);
       Returns a hashref of parameters stemming	from the current request's
       params, plus the	ones supplied.	Keys for which no current param	exists
       will be added, keys with	undefined values will be removed and keys with
       existing	params will be replaced.  Note that you	can supply a true
       value as	the final argument to change behavior with regards to existing
       parameters, appending values rather than	replacing them.

       A quick example:

	 # URI query params foo=1
	 my $hashref = $req->mangle_params({ foo => 2 });
	 # Result is query params of foo=2

       versus append mode:

	 # URI query params foo=1
	 my $hashref = $req->mangle_params({ foo => 2 }, 1);
	 # Result is query params of foo=1&foo=2

       This is the code	behind "uri_with".

   $req->uri_with( { key => 'value' } );
       Returns a rewritten URI object for the current request. Key/value pairs
       passed in will override existing	parameters. You	can remove an existing
       parameter by passing in an undef	value. Unmodified pairs	will be
       preserved.

       You may also pass an optional second parameter that puts	"uri_with"
       into append mode:

	 $req->uri_with( { key => 'value' }, { mode => 'append'	} );

       See "mangle_params" for an explanation of this behavior.

   $req->remote_user
       Returns the value of the	"REMOTE_USER" environment variable.

   $req->user_agent
       Shortcut	to $req->headers->user_agent. Returns the user agent (browser)
       version string.

   $req->io_fh
       Returns a psgix.io bidirectional	socket,	if your	server supports	one.
       Used for	when you want to jailbreak out of PSGI and handle
       bidirectional client server communication manually, such	as when	you
       are using cometd	or websockets.

SETUP METHODS
       You should never	need to	call these yourself in application code,
       however they are	useful if extending Catalyst by	applying a request
       role.

   $self->prepare_headers()
       Sets up the "$res->headers" accessor.

   $self->prepare_body()
       Sets up the body	using HTTP::Body

   $self->prepare_body_chunk()
       Add a chunk to the request body.

   $self->prepare_body_parameters()
       Sets up parameters from body.

   $self->prepare_cookies()
       Parse cookies from header. Sets up a CGI::Simple::Cookie	object.

   $self->prepare_connection()
       Sets up various fields in the request like the local and	remote
       addresses, request method, hostname requested etc.

   $self->prepare_parameters()
       Ensures that the	body has been parsed, then builds the parameters,
       which are combined from those in	the request and	those in the body.

       If parameters have already been set will	clear the parameters and build
       them again.

   $self->env
       Access to the raw PSGI env.

   meta
       Provided	by Moose

AUTHORS
       Catalyst	Contributors, see Catalyst.pm

COPYRIGHT
       This library is free software. You can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2019-01-16		  Catalyst::Request(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | SETUP METHODS | AUTHORS | COPYRIGHT

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

home | help