NAME

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

SYNOPSIS

  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;
  }

ABSTRACT

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.

DESCRIPTION

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

Apache::ParseFormData METHODS

new

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;
  }

parse_result

return the status code after the request is parsed.

param

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";
  }

delete

To delete a parameter provide the name of the parameter:

  $apr->delete("color");

You can delete multiple values:

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

delete_all

This method clear all of the parameters

upload

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_cookie

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

SEE ALSO

libapreq, Apache::Request

CREDITS

This interface is based on the libapreq by Doug MacEachern.

AUTHOR

Henrique Dias, <hdias@aesbuc.pt>

COPYRIGHT AND LICENSE

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.