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. See the libapreq(3) manpage for more details.

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 Apache object as (second) argument.

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

• -attr => $val -type arguments are not supported.

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

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 (in bytes). 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;
 }

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

HOOK_DATA

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

UPLOAD_HOOK

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,
                               );
 $apr->parse;

instance

The instance() class method allows Apache::Request to be a singleton. This means that whenever you call Apache::Request->instance() within a single request you always get the same Apache::Request object back. This solves the problem with creating the Apache::Request object twice within the same request - the symptoms being that the second Apache::Request object will not contain the form parameters because they have already been read and parsed.

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

Note that instance() call will take the same parameters as the above call to new(), however the parameters will only have an effect the first time instance() is called within a single request. Extra parameters will be ignored on subsequent calls to instance() within the same request.

Subrequests receive a new Apache::Request object when they call instance() - the parent request's Apache::Request object is not copied into the subrequest.

Also note that it is unwise to use the parse() method when using instance() because you may end up trying to call it twice, and detecting errors where there are none.

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 (using case-insensitive keys) by mimicing the OO interface of CGI::param. Unlike the CGI.pm version, Apache::Request's param method is very fast- it's now quicker than even mod_perl's native Apache->args method. However, CGI.pm's -attr => $val type arguments are not supported.

    # similar to CGI.pm

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

    # the following differ slightly from CGI.pm

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

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

parms

Get or set the underlying apache parameter table of the Apache::Request object. When invoked without arguments, parms returns a reference to an Apache::Table object that is tied to the Apache::Request object's parameter table. If called with an Apache::Table reference as as argument, the Apache::Request object's parameter table is replaced by the argument's table.

   # $apache_table references an Apache::Table object
   $apr->parms($apache_table); # sets $apr's parameter table

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

upload

Returns a single Apache::Upload object in a scalar context or all Apache::Upload objects in a list 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

Upload objects are implemented as a linked list by libapreq; the next method provides an alternative to using the Apache::Request upload method in a list context:

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

    #functionally the same as:

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

tempname

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 spool file 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 spool file. Check your system's link(2) manpage for details.

SEE ALSO

libapreq(3), Apache::Table(3)

CREDITS

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

AUTHOR

Doug MacEachern, updated for v1.0 by Joe Schaefer

cpanm Apache::Cookie

perl -MCPAN -e shell
install Apache::Cookie