NAME

Apache::Request - Methods for dealing with client request data

SYNOPSIS

    use Apache::Request;
    my $req = Apache::Request->new($r);

DESCRIPTION

Apache::Request adds methods for parsing GET requests and POST requests where Content-type is one of application/x-www-form-urlencoded or multipart/form-data.

Apache::Request METHODS

The interface is designed to mimic CGI.pm 's routines for parsing query parameters. The main differences are

• Apache::Request::new takes an environment-specific object as (second) argument.

• The query parameters are stored as Apache::Table objects, and are therefore parsed using case-insensitive keys.

• The query string is always parsed, even for POST requests.

new

creates a new Apache::Request object with an environment object $r:

    my $req = Apache::Request->new($r);

With mod_perl2, the environment object must be an Apache::RequestRec object. All methods from the environment class are inherited.

The following attributes are optional:

POST_MAX

Limit the size of POST data (in bytes).

DISABLE_UPLOADS

Disable file uploads.

TEMP_DIR

Sets the directory where upload files are spooled. On a *nix-like that supports link(2), the TEMP_DIR should be located on the same file system as the final destination file:

 my $req = Apache::Request->new($r, TEMP_DIR => "/home/httpd/tmp");
 my $upload = $req->upload('file');
 $upload->link("/home/user/myfile") || warn "link failed: $!";

HOOK_DATA [TODO]

Extra configuration info passed to an upload hook. See the description for the next item, UPLOAD_HOOK.

UPLOAD_HOOK [TODO]

Sets up a callback to run whenever file upload data is read. This can be used to provide an upload progress meter during file uploads. Apache will automatically continue writing the original data to $upload->fh after the hook exits.

 my $transparent_hook = sub {
   my ($upload, $buf, $len, $hook_data) = @_;
   warn "$hook_data: got $len bytes for " . $upload->name;
 };

 my $apr = Apache::Request->new($r, 
                                HOOK_DATA => "Note",
                                UPLOAD_HOOK => $transparent_hook,
                               );

param

Get or set (TODO) the request parameters (using case-insensitive keys) by mimicing the OO interface of CGI::param.

    # similar to CGI.pm

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

    # the following differ slightly from CGI.pm

    # assigns multiple values to 'foo'
    $req->param('foo' => [qw(one two three)]); # TODO

    # returns ref to underlying apache table object
    my $table = $req->param; # identical to $apr->parms - see below

parms, params

Get the full parameter table of the Apache::Request object.

   # returns ref to Apache::Request::Table object provided by $apache_table
   my $table = $req->parms;

An optional name parameter can be passed to return the parameter associated with the given name:

   my $param = $req->parms($name);

args

Returns an Apache::Request::Table object containing the query-string parameters of the Apache::Request object.

   my $args = $req->args;

An optional name parameter can be passed to return the query string parameter associated with the given name:

   my $arg = $req->args($name);

body

Returns an Apache::Request::Table object containing the POST data parameters of the Apache::Request object.

   my $body = $req->body;

An optional name parameter can be passed to return the POST data parameter associated with the given name:

   my $param = $req->body($name);

upload

With no arguments, this returns an Apache::Upload::Table object in scalar context, or the names of all Apache::Upload objects in list context.

An optional name parameter can be passed to return the Apache::Upload object associated with the given name:

    my $upload = $apr->upload($name);

SUBCLASSING Apache::Request

If the instances of your subclass are hash references then you can actually inherit from Apache::Request as long as the Apache::Request object is stored in an attribute called "r" or "_r". (The Apache::Request class effectively does the delegation for you automagically, as long as it knows where to find the Apache::Request object to delegate to.) For example:

        package MySubClass;
        use Apache::Request;
        our @ISA = qw(Apache::Request);
        sub new {
                my($class, @args) = @_;
                return bless { r => Apache::Request->new(@args) }, $class;
        }

Apache::Upload METHODS

name

The name of the filefield parameter:

    my $name = $upload->name;

filename

The filename of the uploaded file:

    my $filename = $upload->filename;

bb [replaces fh]

The APR::Brigade containing the contents of the uploaded file.

size [TODO]

The size of the file in bytes:

    my $size = $upload->size;

info

The additional header information for the uploaded file. Returns a hash reference tied to the Apache::Table class. An optional key argument can be passed to return the value of a given header rather than a hash reference. Examples:

    my $info = $upload->info;
    while (my($key, $val) = each %$info) {
        ...
    }

    my $val = $upload->info("Content-type");

type [TODO]

Returns the Content-Type for the given Apache::Upload object:

    my $type = $upload->type;
    #same as
    my $type = $upload->info("Content-Type");

tempname [XXX- Does this mesh with brigade API?]

Provides the name of the spool file. This method is reserved for debugging purposes, and is possibly subject to change in a future version of Apache::Request.

link

To avoid recopying the upload's internal tempfile brigade on a *nix-like system, link will create a hard link to it:

  my $upload = $apr->upload('file');
  $upload->link("/path/to/newfile") or
      die sprintf "link from '%s' failed: $!", $upload->tempname;

Typically the new name must lie on the same file system as the brigade's tempfile. Check your system's link(2) manpage for details.

SEE ALSO

APR::Table(3)

CREDITS

This interface is based on the original pure Perl version by Lincoln Stein.

AUTHORS

Doug MacEachern, Joe Schaefer, Steve Hay.

MISSING DOCS

$req->config, Apache::Request::Table, Apache::Upload::Table.

cpanm MySubClass

perl -MCPAN -e shell
install MySubClass