Apache::Request - Methods for dealing with client request data
use Apache::Request ();
my $apr = Apache::Request->new($r);
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.
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:
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 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;
}
Sets the directory where upload files are spooled. On a *nix-like that
supports link(2), the TEMP_DIR should be placed 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: $!";
Extra configuration info to be passed to and upload hook. See next item for details.
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;
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.
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; }
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)]);
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);
The name of the filefield parameter:
my $name = $upload->name;
The filename of the uploaded file:
my $filename = $upload->filename;
The filehandle pointing to the uploaded file:
my $fh = $upload->fh;
while (<$fh>) {
...
}
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");
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) {
...
}
Provides the name of the spool file.
To avoid recopying the spool file on a Unix-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.
libapreq(3)
This interface is based on the original pure Perl version by Lincoln Stein.
Doug MacEachern