The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

PCGI - Perl Common Gateway Interface Class

SYNOPSIS

  use PCGI qw(:all);

  $query = PCGI->new();

  # Query's parsing settings.
  # Note: settings of specified group can be changed only before
  #       parsing activation of this group

  $query->set(
    GET => {
      IncEmpty    => $bool,     # No
      EscNull     => $bool      # Yes
    },
    COOKIE => {
      IncEmpty    => $bool,     # No
      EscNull     => $bool      # Yes
    },
    POST => {
      IncEmpty    => $bool,     # No
      EscNull     => $bool,     # Yes
      MaxLoops    => $number,   # 256
      MaxSize     => $number,   # 2Mb
      MaxNameSize => $number,   # 128b
      MaxValsSize => $number    # 2Mb
    },
    MULTI => {
      IncEmpty    => $bool,     # No
      EscNull     => $bool,     # Yes
      MaxLoops    => $number,   # 256
      MaxSize     => $number,   # 32Mb
      MaxNameSize => $number,   # 128b
      MaxValsSize => $number,   # 2Mb
      MaxFiles    => $number,   # 16
      TempDir     => $tempdir   # Autodetect
    }
  );

  # Errors checking.
  # Note: this method also activates parsing of POST query. If
  #       query isn't POST or wasn't errors, then will be returned
  #       empty string

  $errstr = $query->errstr();

  # Access to parsed query's.
  # Note: parsing of specific query is activates automatically

  @names  = $query->GET();
  @values = $query->GET($name);
  $value  = $query->GET($name);

  @names  = $query->COOKIE();
  $value  = $query->COOKIE($name);

  @names  = $query->POST();
  @values = $query->POST($name);
  $value  = $query->POST($name);

  @names  = $query->FILE();
  @files  = $query->FILE($name);
  $file   = $query->FILE($name);

  $full = $file->{full};
  $base = $file->{base};
  $temp = $file->{temp};
  $mime = $file->{mime};
  $size = $file->{size};

  # Handling response

  $query->header( $param => undef ); # delete
  $query->header( $param => $value, ... ); # add single value
  $query->header( $param => \@values, ... ); # add multiple value

  $query->setcookie( $name => undef ); # delete
  $query->setcookie( $name => $value,  # add
    {
      Path    => $path,
      Domain  => $domain,
      Expires => $utime,
      Secure  => $bool,
      Raw     => $bool
    }
  );

  $query->sendheader();

  # Utilite method(s)

  $value = $query->env($name);

  # Utilite functions

  $string  = httpdate($utime);
  $string  = trim($string);
  $encoded = urlencode($string);
  $decoded = urldecode($string);

DESCRIPTION

This is Perl module for fastest and full safely works with Common Gateway Interface. Required little memory for work, and can safely parsing a big or giant POST query's.

METHODS

new()

The constructor method instantiates a new PCGI object.

DESTROY()

The destructor method cleaning up memory and deleting existings temporary files.

set( GROUP => { NAME => VALUE }, ... )

Method for changing settings of query's parsing.

Note: settings of specified group can be changed only before parsing activation of this group.

GROUP

Name of settings group:

GET

Settings of GET query parsing:

IncEmpty - Boolean value. Include or not parameters with empty values. Undefined by default.

EscNull - Boolean value. Escaping or not simbols with zero code from any places, where it needed. Default value is 1 and strongly not recommended to change this parameter!

Settings of COOKIE string parsing:

IncEmpty - ...

EscNull - ...

POST

Settings of POST query parsing:

IncEmpty - ...

EscNull - ...

MaxLoops - This is very important parameter! Defines limit for quantity of cycle iterations during parsing query. Usualy quantity of cycle iterations is equal to quantity of elements in HTML form, or some more. Default value is 256.

MaxSize - Definition maximal valid size in bytes for query. Default value is 2Mb.

MaxNameSize - Definition maximal valid size in bytes for every name of parameter in query. Default value is 128.

MaxValsSize - Definition maximal valid size in bytes of summary values size. Default value is 2Mb.

Warning: only for this settings group. MaxSize, MaxNameSize and MaxValsSize means size's of undecoded data!

MULTI

Settings of multipart POST query parsing:

IncEmpty - ...

EscNull - ...

MaxLoops - ...

MaxSize - ... Default value is 32Mb.

MaxNameSize - ...

MaxValsSize - ...

MaxFiles - Definition maximal quantity of uploading files. Defalut value is 16.

TempDir - Temporary directory manual definition. Use undefined value for autodetect. Undefined by default.

errstr()

This method activates the parsing of POST query (if wasn't parsed before) and returns HTTP standard status of this operation. Empty string mean, what POST query was parsed successfuly. Also empty string returns at non-POST requests.

Possible reasons of request fatal errors:

  • size of POST data is more 'MaxSize' parameter;

  • quantity of cycle iterations is more 'MaxLoops' parameter;

  • found name of parameter with size more 'MaxNameSize' parameter;

  • sumary values size is more 'MaxValsSize' parameter;

  • malformed POST data;

  • errors in request header fields.

Note: also at any of that parsing errors all POST data, what was parsed before, will be truncated.

GET( [ NAME ] )

In scalar context returns first one element value, specified by NAME. If element not exists, then returns undef value.

In array context returns array of element values, specified by NAME.

If name is not specified, then returns array with all available names.

COOKIE()

...

Only one difference. For every NAME of parameter can be maximum one value.

POST()

...

FILE()

...

If value of element, specified by NAME, is defined, then this is reference to hash array with parameters:

full - alltimes defined and not empty string. Full filename from client.

base - alltimes defined and not empty string. Base name of full filename. Cannot contains symbols "\", "/" and ":".

temp - path to local temporary file, created in mode 0600 on POSIX systems.

mime - alltimes defined, but can be empty. This is client specified mime type. Can contains anything ;-)

size - alltimes defined number. Real size of temporary file.

header( NAME => VALUE, ... )

Method for setting (or deleting) response header parameters.

Note: for changing HTTP status in response, please, use the 'status' parameter.

NAME

Name of parameter. Must be defined and not empty string. All symbols '-' can be changed to symbols '_'. Case is not mutter.

VALUE

This is string with new value or reference to array with many new values. In case of undefined value, parameter will be deleted.

setcookie( NAME => VALUE, { ... Attributes ... } )

Method for setting (or deleting) HTTP cookie's.

NAME

Name of cookie. Must be defined and not empty string.

VALUE

This is string with new value. In case of undefined value, will be generated code for deleting cookie.

Attributes:

These optional attributes are available:

Expires - time in UNIX format. Specifies a "time to live" for this cookie. By default setted cookie will be available before browser closing.

Domain - specifies the domain for which the cookie is valid.

Path - specifies the subset of URLs to which this cookie applies.

Secure - if true, then directs the user agent to use only (unspecified) secure means to contact the origin server whenever it sends back this cookie.

Raw - if true, then value will be sent as is. Otherwise, by default, value will be url-encoded.

sendheader()

Method for sending header. Can be used only once.

env( NAME )

Simple wrapper for array $ENV. Only one difference, - never returns undefined values. NAME must be defined. Example:

  if( $query->env('REQUEST_METHOD') eq 'POST' ) {
    # ...
  }
httpdate( UTIME )

HTTP date formater. Returns string, - date, formed by HTTP standard.

UTIME

Time in UNIX format. Current time by default.

trim( STRING )

Returns STRING copy, but without leading and trailing spaces. STRING must be defined.

urldecode( STRING )

Returns url-decoded STRING. String must be defined.

urlencode( STRING )

Returns url-encoded STRING. String must be defined.

UTF-8 SUPPORT

This module works only with raw data! But, URL-encoded data in UTF-8 mode (%uXXXX) will be decoded correctly.

EBCDIC SUPPORT

No support. Only ACSII platforms supported.

REQUIREMENT

  • Perl 5.005 or higher;

  • Stream::Reader 0.09 or higher;

  • Fresh enough version of Apache web server.

SECURITY

This module can safely works with any size's of POST requests. It is not realy mutter, especially for multipart POST ;-)

Warning: but be enough careful with parsing settings of POST and MULTI groups. Default setting should be enough for mostly people. I hope so..

MOD_PERL SUPPORT

Supported transparently. You don't need think about that :-) All methods works the same.

Note: All examples works the same under mod_perl too.

EXAMPLES

Please visit catalogue examples/ in this module distribution.

CREDITS

Special thanks to:

  • Andrey Fimushkin, <plohaja@mail.ru>

  • Green Kakadu, <gnezdo@gmail.com>

AUTHOR

Andrian Zubko aka Ondr, <ondr@cpan.org>