NAME

HTTP::Engine::Request - Portable HTTP request object

SYNOPSIS

    # normally a request object is passed into your handler
    sub handle_request {
        my $req = shift;
   };

DESCRIPTION

HTTP::Engine::Request provides a consistent API for request objects across web server enviroments.

METHODS

new

    HTTP::Engine::Request->new(
        request_builder => $BUILDER,
        _connection => {
            env           => \%ENV,
            input_handle  => \*STDIN,
            output_handle => \*STDOUT,
        },
        %args
    );

Normally, new() is not called directly, but a pre-built HTTP::Engine::Request object is passed for you into your request handler. You may build your own, following the example above. The $BUILDER may be one of HTTP::Engine::RequestBuilder::CGI or HTTP::Engine::RequestBuilder::NoEnv.

ATTRIBUTES

builder_options: configuration for control of HTTP::Engine::RequestBuilder.

disable_raw_body

$req->raw_body is not saved.

When receiving upload of a big file, it uses in order to prevent raw_body becoming large.

raw_body is enabled by the default. because of back compatibility.

  $req->upload('file1');
  is $req->raw_body, '...some contents...';
  $req->builder_options->{disable_raw_body} = 1;
  $req->upload('file2');
  is $req->raw_body, '';
  $req->builder_options->{disable_raw_body} = 0;
  $req->upload('file1');
  is $req->raw_body, '...some contents...';

upload_tmp

change temporarily directory to store upload file. It changes of default temporarily directory by HTTP::Body.

generally use File::Temp.

  $req->builder_options->{upload_tmp} = File::Temp->newdir;

for lazy make directory

  $req->builder_options->{upload_tmp} = sub { File::Temp->newdir };

In these examples, if request processing finishes, upload files will be deleted.

address

Returns the IP address of the client.

cookies

Returns a reference to a hash containing the cookies

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 request uri (like $ENV{REQUEST_URI})

query_parameters

Returns a reference to a hash containing query string (GET) parameters. Values can be either a scalar or an arrayref containing scalars.

secure

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

proxy_request

Returns undef or uri, if it is proxy request, uri of a connection place is returned.

uri

Returns a URI object for the current request. Stringifies to the URI text.

user

Returns REMOTE_USER.

raw_body

Returns string containing body(POST).

headers

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

base

Contains the URI base. This will always have a trailing slash.

hostname

Returns the hostname of the client.

http_body

Returns an HTTP::Body object.

parameters

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

uploads

Returns a reference to a hash containing uploads. Values can be either a HTTP::Engine::Request::Upload object, or an arrayref of HTTP::Engine::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.

cookie

A convenient method to access $req->cookies.

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

param

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

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

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

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

path

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

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

uri_with

Returns a rewritten URI object for the current request. Key/value pairs passed in will override existing parameters. Unmodified pairs will be preserved.

as_http_request

convert HTTP::Engine::Request to HTTP::Request.

$req->absolute_url($location)

convert $location to absolute uri.

AUTHORS

Kazuhiro Osawa and HTTP::Engine Authors.

THANKS TO

Catalyst::Request