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

FreeBSD Manual Pages

  
 
  

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

NAME
       Plack::Request -	Portable HTTP request object from PSGI env hash

SYNOPSIS
	 use Plack::Request;

	 my $app_or_middleware = sub {
	     my	$env = shift; #	PSGI env

	     my	$req = Plack::Request->new($env);

	     my	$path_info = $req->path_info;
	     my	$query	   = $req->parameters->{query};

	     my	$res = $req->new_response(200);	# new Plack::Response
	     $res->finalize;
	 };

DESCRIPTION
       Plack::Request provides a consistent API	for request objects across web
       server environments.

CAVEAT
       Note that this module is	intended to be used by Plack middleware
       developers and web application framework	developers rather than
       application developers (end users).

       Writing your web	application directly using Plack::Request is certainly
       possible	but not	recommended: it's like doing so	with mod_perl's
       Apache::Request:	yet too	low level.

       If you're writing a web application, not	a framework, then you're
       encouraged to use one of	the web	application frameworks that support
       PSGI (<http://plackperl.org/#frameworks>), or see modules like
       HTTP::Engine to provide higher level Request and	Response API on	top of
       PSGI.

METHODS
       Some of the methods defined in the earlier versions are deprecated in
       version 0.99. Take a look at "INCOMPATIBILITIES".

       Unless otherwise	noted, all methods and attributes are read-only, and
       passing values to the method like an accessor doesn't work like you
       expect it to.

   new
	   Plack::Request->new(	$env );

       Creates a new request object.

ATTRIBUTES
       env Returns the shared PSGI environment hash reference. This is a
	   reference, so writing to this environment passes through during the
	   whole PSGI request/response cycle.

       address
	   Returns the IP address of the client	("REMOTE_ADDR").

       remote_host
	   Returns the remote host ("REMOTE_HOST") of the client. It may be
	   empty, in which case	you have to get	the IP address using "address"
	   method and resolve on your own.

       method
	   Contains the	request	method ("GET", "POST", "HEAD", etc).

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

       request_uri
	   Returns the raw, undecoded request URI path.	You probably do	NOT
	   want	to use this to dispatch	requests.

       path_info
	   Returns PATH_INFO in	the environment. Use this to get the local
	   path	for the	requests.

       path
	   Similar to "path_info" but returns "/" in case it is	empty. In
	   other words,	it returns the virtual path of the request URI after
	   "$req->base". See "DISPATCHING" for details.

       query_string
	   Returns QUERY_STRING	in the environment. This is the	undecoded
	   query string	in the request URI.

       script_name
	   Returns SCRIPT_NAME in the environment. This	is the absolute	path
	   where your application is hosted.

       scheme
	   Returns the scheme ("http" or "https") of the request.

       secure
	   Returns true	or false, indicating whether the connection is secure
	   (https).

       body, input
	   Returns "psgi.input"	handle.

       session
	   Returns (optional) "psgix.session" hash. When it exists, you	can
	   retrieve and	store per-session data from and	to this	hash.

       session_options
	   Returns (optional) "psgix.session.options" hash.

       logger
	   Returns (optional) "psgix.logger" code reference. When it exists,
	   your	application is supposed	to send	the log	message	to this
	   logger, using:

	     $req->logger->({ level => 'debug',	message	=> "This is a debug message" });

       cookies
	   Returns a reference to a hash containing the	cookies. Values	are
	   strings that	are sent by clients and	are URI	decoded.

	   If there are	multiple cookies with the same name in the request,
	   this	method will ignore the duplicates and return only the first
	   value. If that causes issues	for you, you may have to use modules
	   like	CGI::Simple::Cookie to parse "$request->header('Cookies')" by
	   yourself.

       query_parameters
	   Returns a reference to a hash containing query string (GET)
	   parameters. This hash reference is Hash::MultiValue object.

       body_parameters
	   Returns a reference to a hash containing posted parameters in the
	   request body	(POST).	As with	"query_parameters", the	hash reference
	   is a	Hash::MultiValue object.

       parameters
	   Returns a Hash::MultiValue hash reference containing	(merged) GET
	   and POST parameters.

       content,	raw_body
	   Returns the request content in an undecoded byte string for POST
	   requests.

       uri Returns an URI object for the current request. The URI is
	   constructed using various environment values	such as	"SCRIPT_NAME",
	   "PATH_INFO",	"QUERY_STRING",	"HTTP_HOST", "SERVER_NAME" and
	   "SERVER_PORT".

	   Every time this method is called it returns a new, cloned URI
	   object.

       base
	   Returns an URI object for the base path of current request. This is
	   like	"uri" but only contains	up to "SCRIPT_NAME" where your
	   application is hosted at.

	   Every time this method is called it returns a new, cloned URI
	   object.

       user
	   Returns "REMOTE_USER" if it's set.

       headers
	   Returns an HTTP::Headers::Fast object containing the	headers	for
	   the current request.

       uploads
	   Returns a reference to a hash containing uploads. The hash
	   reference is	a Hash::MultiValue object and values are
	   Plack::Request::Upload objects.

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

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

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

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

       referer
	   Shortcut to $req->headers->referer.

       user_agent
	   Shortcut to $req->headers->user_agent.

       param
	   Returns GET and POST	parameters with	a CGI.pm-compatible param
	   method. This	is an alternative method for accessing parameters in
	   $req->parameters just in case you want the compatibility with
	   CGI.pm objects.

	   You are not recommended to use this method since it is easy to
	   misuse in a list context such as inside a hash constructor or
	   method arguments. Use "parameters" and Hash::MultiValue instead.

	   Unlike CGI.pm, it does not allow setting or modifying query
	   parameters.

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

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

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

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

       new_response
	     my	$res = $req->new_response;

	   Creates a new Plack::Response object. Handy to remove dependency on
	   Plack::Response in your code	for easy subclassing and duck typing
	   in web application frameworks, as well as overriding	Response
	   generation in middlewares.

   Hash::MultiValue parameters
       Parameters that can take	one or multiple	values (i.e. "parameters",
       "query_parameters", "body_parameters" and "uploads") store the hash
       reference as a Hash::MultiValue object. This means you can use the hash
       reference as a plain hash where values are always scalars (NOT array
       references), so you don't need to code ugly and unsafe "ref ... eq
       'ARRAY'"	anymore.

       And if you explicitly want to get multiple values of the	same key, you
       can call	the "get_all" method on	it, such as:

	 my @foo = $req->query_parameters->get_all('foo');

       You can also call "get_one" to always get one parameter independent of
       the context (unlike "param"), and even call "mixed" (with
       Hash::MultiValue	0.05 or	later) to get the traditional hash reference,

	 my $params = $req->parameters->mixed;

       where values are	either a scalar	or an array reference depending	on
       input, so it might be useful if you already have	the code to deal with
       that ugliness.

   PARSING POST	BODY and MULTIPLE OBJECTS
       The methods to parse request body ("content", "body_parameters" and
       "uploads") are carefully	coded to save the parsed body in the
       environment hash	as well	as in the temporary buffer, so you can call
       them multiple times and create Plack::Request objects multiple times in
       a request and they should work safely, and won't	parse request body
       more than twice for the efficiency.

DISPATCHING
       If your application or framework	wants to dispatch (or route) actions
       based on	request	paths, be sure to use "$req->path_info"	not
       "$req->uri->path".

       This is because "path_info" gives you the virtual path of the request,
       regardless of how your application is mounted. If your application is
       hosted with mod_perl or CGI scripts, or even multiplexed	with tools
       like Plack::App::URLMap,	request's "path_info" always gives you the
       action path.

       Note that "path_info" might give	you an empty string, in	which case you
       should assume that the path is "/".

       You will	also want to use "$req->base" as a base	prefix when building
       URLs in your templates or in redirections. It's a good idea for you to
       subclass	Plack::Request and define methods such as:

	 sub uri_for {
	     my($self, $path, $args) = @_;
	     my	$uri = $self->base;
	     $uri->path($uri->path . $path);
	     $uri->query_form(@$args) if $args;
	     $uri;
	 }

       So you can say:

	 my $link = $req->uri_for('/logout', [ signoff => 1 ]);

       and if "$req->base" is "/app" you'll get	the full URI for
       "/app/logout?signoff=1".

INCOMPATIBILITIES
       In version 0.99,	many utility methods are removed or deprecated,	and
       most methods are	made read-only.	These methods were deleted in version
       1.0001.

       All parameter-related methods such as "parameters", "body_parameters",
       "query_parameters" and "uploads"	now contains Hash::MultiValue objects,
       rather than scalar or an	array reference	depending on the user input
       which is	insecure. See Hash::MultiValue for more	about this change.

       "$req->path" method had a bug, where the	code and the document was
       mismatching. The	document was suggesting	it returns the sub request
       path after "$req->base" but the code was	always returning the absolute
       URI path. The code is now updated to be an alias	of "$req->path_info"
       but returns "/" in case it's empty. If you need the older behavior,
       just call "$req->uri->path" instead.

       Cookie handling is simplified, and doesn't use CGI::Simple::Cookie
       anymore,	which means you	CAN NOT	set array reference or hash reference
       as a cookie value and expect it be serialized. You're always required
       to set string value, and	encoding or decoding them is totally up	to
       your application	or framework. Also, "cookies" hash reference now
       returns strings for the cookies rather than CGI::Simple::Cookie
       objects,	which means you	no longer have to write	a wacky	code such as:

	 $v = $req->cookies->{foo} ? $req->cookies->{foo}->value : undef;

       and instead, simply do:

	 $v = $req->cookies->{foo};

AUTHORS
       Tatsuhiko Miyagawa

       Kazuhiro	Osawa

       Tokuhiro	Matsuno

SEE ALSO
       Plack::Response HTTP::Request, Catalyst::Request

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

perl v5.24.1			  2015-12-06		     Plack::Request(3)

NAME | SYNOPSIS | DESCRIPTION | CAVEAT | METHODS | ATTRIBUTES | DISPATCHING | INCOMPATIBILITIES | AUTHORS | SEE ALSO | LICENSE

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

home | help