The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Web-Request-0.04
River stage one • 6 direct dependents • 8 total dependents
5 ++
/ Web::Request

NAME

Web::Request - common request class for web frameworks

VERSION

version 0.04

SYNOPSIS

  use Web::Request;

  my $app = sub {
      my ($env) = @_;
      my $req = Web::Request->new_from_env($env);
      # ...
  };

DESCRIPTION

Web::Request is a request class for PSGI applications. It provides access to all of the information received in a request, generated from the PSGI environment. The available methods are listed below.

Note that Web::Request objects are intended to be (almost) entirely read-only - although some methods (headers, uri, etc) may return mutable objects, changing those objects will have no effect on the actual environment, or the return values of any of the other methods. Doing this is entirely unsupported. In addition, the return values of most methods that aren't direct accesses to env are cached, so if you do modify the actual environment hashref, you should create a new Web::Request object for it.

The one exception is the encoding attribute, which is allowed to be modified. Changing the encoding will change the return value of any subsequent calls to content, query_parameters, all_query_parameters, body_parameters, and all_body_parameters.

Web::Request is based heavily on Plack::Request, but with the intention of growing to become more generally useful to end users (rather than just framework and middleware developers). In the future, it is expected to grow in functionality to support a lot more convenient functionality, while Plack::Request has a more minimalist goal.

METHODS

address

Returns the IP address of the remote client.

remote_host

Returns the hostname of the remote client. May be empty.

protocol

Returns the protocol (HTTP/1.0, HTTP/1.1, etc.) used in the current request.

method

Returns the HTTP method (GET, POST, etc.) used in the current request.

port

Returns the local port that this request was made on.

host

Returns the contents of the HTTP Host header. If it doesn't exist, falls back to recreating the host from the SERVER_NAME and SERVER_PORT variables.

path

Returns the request path for the current request. Unlike path_info, this will never be empty, it will always start with /. This is most likely what you want to use to dispatch on.

path_info

Returns the request path for the current request. This can be '' if script_name ends in a /. This can be appended to script_name to get the full (absolute) path that was requested from the server.

script_name

Returns the absolute path where your application is mounted. It may be '' (in which case, path_info will start with a /).

request_uri

Returns the raw, undecoded URI path (the literal path provided in the request, so /foo%20bar in GET /foo%20bar HTTP/1.1). You most likely want to use path, path_info, or script_name instead.

scheme

Returns http or https depending on the scheme used in the request.

session

Returns the session object, if a middleware is used which provides one. See PSGI::Extensions.

session_options

Returns the session options hashref, if a middleware is used which provides one. See PSGI::Extensions.

logger

Returns the logger object, if a middleware is used which provides one. See PSGI::Extensions.

uri

Returns the full URI used in the current request, as a URI object.

base_uri

Returns the base URI for the current request (only the components up through script_name) as a URI object.

headers

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

content_length

The length of the content, in bytes. Corresponds to the Content-Length header.

content_type

The MIME type of the content. Corresponds to the Content-Type header.

content_encoding

The encoding of the content. Corresponds to the Content-Encoding header.

referer

Returns the value of the Referer header.

user_agent

Returns the value of the User-Agent header.

header($name)

Shortcut for $req->headers->header($name).

cookies

Returns a hashref of cookies received in this request. The values are URI decoded.

content

Returns the content received in this request, decoded based on the value of encoding.

param($param)

Returns the parameter value for the parameter named $param. Returns the last parameter given if more than one are passed.

parameters

Returns a hashref of parameter names to values. If a name is given more than once, the last value is provided.

all_parameters

Returns a hashref where the keys are parameter names and the values are arrayrefs holding every value given for that parameter name. All parameters are stored in an arrayref, even if there is only a single value.

query_parameters

Like parameters, but only return the parameters that were given in the query string.

all_query_parameters

Like all_parameters, but only return the parameters that were given in the query string.

body_parameters

Like parameters, but only return the parameters that were given in the request body.

all_body_parameters

Like all_parameters, but only return the parameters that were given in the request body.

uploads

Returns a hashref of upload objects (instances of upload_class). If more than one upload is provided with a given name, returns the last one given.

all_uploads

Returns a hashref where the keys are upload names and the values are arrayrefs holding an upload object (instance of upload_class) for every upload given for that name. All uploads are stored in an arrayref, even if there is only a single value.

new_response(@params)

Returns a new response object, passing @params to its constructor.

env

Returns the PSGI environment that was provided in the constructor (or generated from the HTTP::Request, if new_from_request was used).

encoding($enc)

Returns the encoding that was provided in the constructor. You can also pass an encoding name to this method to set the encoding that will be used to decode the content and encode the response. For instance, you can set the encoding to UTF-8 in order to read the body content and parameters, and then set the encoding to undef at the end of the handler in order to indicate that the response should not be encoded (for instance, if it is a binary file).

response_class

Returns the name of the class to use when creating a new response object via new_response. Defaults to Web::Response. This can be overridden in a subclass.

upload_class

Returns the name of the class to use when creating a new upload object for uploads or all_uploads. Defaults to Web::Request::Upload. This can be overridden in a subclass.

default_encoding

Returns the name of the default encoding to use for decoding. Defaults to iso8859-1. This can be overridden in a subclass.

CONSTRUCTORS

new_from_env($env)

Create a new Web::Request object from a PSGI environment hashref.

new_from_request($request)

Create a new Web::Request object from a HTTP::Request object.

new(%params)

Create a new Web::Request object with named parameters. Valid parameters are:

env

A PSGI environment hashref. Required.

encoding

The encoding to use for decoding all input in the request and encoding all output in the response. Defaults to the value of default_encoding. If undef is passed, no encoding or decoding will be done.

BUGS

No known bugs.

Please report any bugs through RT: email bug-web-request at rt.cpan.org, or browse to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Web-Request.

SEE ALSO

Plack::Request - Much of this module's API and implementation were taken from Plack::Request.

SUPPORT

You can find this documentation for this module with the perldoc command.

    perldoc Web::Request

You can also look for information at:

AUTHOR

Jesse Luehrs <doy at cpan dot org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Jesse Luehrs.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.