NAME

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

SYNOPSIS

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

DESCRIPTION

Apache::Request is a subclass of the Apache class, which 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

new

Create a new Apache::Request object with an Apache request_rec object:

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

All methods from the Apache class are inherited.

The following attributes are optional:

POST_MAX

Limit the size of POST data. Apache::Request::parse will return an error code if the size is exceeded:

 my $apr = Apache::Request->new($r, POST_MAX => 1024);
 my $status = $apr->parse;

 if ($status) {
     my $errmsg = $apr->notes("error-notes");
     ...
     return $status;
 }

DISABLE_UPLOADS

Disable file uploads. Apache::Request::parse will return an error code if a file upload is attempted:

 my $apr = Apache::Request->new($r, DISABLE_UPLOADS => 1);
 my $status = $apr->parse;

 if ($status) {
     my $errmsg = $apr->notes("error-notes");
     ...
     return $status;
 }

parse

The parse method does the actual work of parsing the request. It is called for you by the accessor methods, so it is not required but can be useful to provide a more user-friendly message should an error occur:

    my $r = shift;
    my $apr = Apache::Request->new($r); 
 
    my $status = $apr->parse; 
    unless ($status == OK) { 
        $apr->custom_response($status, $apr->notes("error-notes")); 
        return $status; 
    } 

param

Get or set request parameters:

    my $value = $apr->param('foo');
    my @values = $apr->param('foo');
    my @params = $apr->param;
    $apr->param('foo' => [qw(one two three)]);

upload

Returns a single Apache::Upload object in a scalar context or all Apache::Upload objects in an array context:

    my $upload = $apr->upload;
    my $fh = $upload->fh;
    my $lines = 0; 
    while(<$fh>) { 
        ++$lines; 
        ...
    } 

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

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

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;

fh

The filehandle pointing to the uploaded file:

    my $fh = $upload->fh;
    while (<$fh>) {
        ...
    }

size

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

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

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

next

As an alternative to using the Apache::Request upload method in an array context:

    for (my $upload = $apr->upload; $upload; $upload = $upload->next) {
        ...
    }

    #functionally the same as:

    for my $upload ($apr->upload) {
        ...
    }

CREDITS

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

AUTHOR

Doug MacEachern