Apache::ParseFormData - Perl extension for dealing with client request data

  use Apache::RequestRec ();
  use Apache::RequestUtil ();
  use Apache::Const -compile => qw(DECLINED OK);
  use Apache::ParseFormData;

  sub handler {
    my $r = shift;
    my $apr = Apache::ParseFormData->new($r);

    my $scalar = 'abc';
    $apr->param('scalar_test' => $scalar);
    my $s_test = $apr->param('scalar_test');
    print $s_test;

    my @array = ('a', 'b', 'c');
    $apr->param('array_test' => \@array);
    my @a_test = $apr->param('array_test');
    print $a_test[0];

    my %hash = (
      a => 1,
      b => 2,
      c => 3,
    );
    $apr->param('hash_test' => \%hash);
    my %h_test = $apr->param('hash_test');
    print $h_test{'a'};

    $apr->notes->clear();

    return Apache::OK;
  }

The Apache::ParseFormData module allows you to easily decode and parse form and query data, even multipart forms generated by "file upload". This module only work with mod_perl 2.

Apache::ParseFormData extension parses a GET and POST requests, with multipart form data input stream, and saves any files/parameters encountered for subsequent use.

Create a new Apache::ParseFormData object. The methods from Apache class are inherited. The optional arguments which can be passed to the method are the following:

temp_dir

Directory where the upload files are stored.

disable_uploads

Disable file uploads.

  my $apr = Apache::ParseFormData->new($r, disable_uploads => 1);

  my $status = $apr->parse_result;
  unless($status == Apache::OK) {
    my $error = $apr->notes->get("error-notes");
    ...
    return $status;
  }

post_max

Limit the size of POST data.

  my $apr = Apache::ParseFormData->new($r, post_max => 1024);

  my $status = $apr->parse_result;
  unless($status == Apache::OK) {
    my $error = $apr->notes->get("error-notes");
    ...
    return $status;
  }

return the status code after the request is parsed.

Like CGI.pm you can add or modify the value of parameters within your script.

  my $scalar = 'abc';
  $apr->param('scalar_test' => $scalar);
  my $s_test = $apr->param('scalar_test');
  print $s_test;

  my @array = ('a', 'b', 'c');
  $apr->param('array_test' => \@array);
  my @a_test = $apr->param('array_test');
  print $a_test[0];

  my %hash = (
    a => 1,
    b => 2,
    c => 3,
  );
  $apr->param('hash_test' => \%hash);
  my %h_test = $apr->param('hash_test');
  print $h_test{'a'};

You can create a parameter with multiple values by passing additional arguments:

  $apr->param(
    'color'    => "red",
    'numbers'  => [0,1,2,3,4,5,6,7,8,9],
    'language' => "perl",
  );

Fetching the names of all the parameters passed to your script:

  foreach my $name (@names) {
    my $value = $apr->param($name);
    print "$name => $value\n";
  }

To delete a parameter provide the name of the parameter:

  $apr->delete("color");

You can delete multiple values:

  $apr->delete("color", "nembers");

This method clear all of the parameters

You can access the name of an uploaded file with the param method, just like the value of any other form element.

  my %file_hash = $apr->param('file');
  my $filename = $file_hash{'filename'};
  my $content_type = $file_hash{'type'};
  my $size = $file_hash{'size'};

  my ($fh, $path) = $apr->upload('file_0');

  for my $form_name ($apr->upload()) {
    my ($fh, $path) = $apr->upload($form_name);

    while(<$fh>) {
      print $_;
    }

    my %file_hash = $apr->param($form_name);
    my $filename = $file_hash{'filename'};
    my $content_type = $file_hash{'type'};
    my $size = $file_hash{'size'};
    unlink($path);
  }

Set the cookies before send any printable data to client.

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

  $apr->set_cookie(
    name    => "foo",
    value   => "bar",
    path    => "/cgi-bin/database",
    expires => time + 3600,
    secure  => 1,
    domain  => ".capricorn.com",
  );

Get the value of foo:

  $apr->param('foo');

Clean cookie:

  $apr->set_cookie(
    name    => "foo",
    value   => "",
    expires => time - 3600,
  );

libapreq, Apache::Request

This interface is based on the libapreq by Doug MacEachern.

Henrique Dias, <hdias@aesbuc.pt>

Copyright 2003 by Henrique Dias

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.