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, );
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.
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.