Apache::Request - Methods for dealing with client request data
use Apache::Request; my $req = Apache::Request->new($r);
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.
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.
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:
my $req = Apache::Request->new($r, TEMP_DIR => "/home/httpd/tmp"); my $upload = $req->upload('file'); $upload->link("/home/user/myfile") || warn "link failed: $!";
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, );
The default (and only) behavior of Apache::Request is to intelligently
cache POST data for the duration of the request. Thus there is no longer
the need for a separate instance()
method as existed in Apache::Request
for Apache 1.3 - all POST data is always available from each and every
Apache::Request object created during the request's lifetime.
If you need an instance()
method to make ease the pains of porting to
Apache 2.0, you can add this shortcut to your startup.pl
:
use Apache::Request; *Apache::Request::instance = \&Apache::Request::new;
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
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);
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);
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);
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);
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; }
The name of the filefield parameter:
my $name = $upload->name;
The filename of the uploaded file:
my $filename = $upload->filename;
The APR::Brigade containing the contents of the uploaded file.
The size of the file in bytes:
my $size = $upload->size;
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");
Returns the Content-Type for the given Apache::Upload object:
my $type = $upload->type; #same as my $type = $upload->info("Content-Type");
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.
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.
Reads the full contents of a file upload into the scalar argument. The return value is currently an APR status code (0 on success, error otherwise), but this may change in a future release (to bring this function in line with similar read-type functions in mp2).
# print out the upload file my $contents; print $contents if $upload->slurp($contents) == 0;
APR::Table(3)
This interface is based on the original pure Perl version by Lincoln Stein.
Doug MacEachern, Joe Schaefer, Steve Hay.
$req->config, Apache::Request::Table, Apache::Upload::Table.