NAME

CGI::Lite - Process and decode WWW forms and cookies

SYNOPSIS

use CGI::Lite ();

my $cgi = CGI::Lite->new ();

$cgi->set_directory ('/some/dir') or die "Directory cannot be set.\n";
$cgi->add_mime_type ('text/csv');

my $cookies = $cgi->parse_cookies;
my $form    = $cgi->parse_new_form_data;

my $status  = $cgi->is_error;
if ($status) {
    my $message = $cgi->get_error_message;
    die $message;
}

DESCRIPTION

This module can be used to decode form data, query strings, file uploads and cookies in a very simple manner.

It has only one dependency and is therefore relatively fast to instantiate. This makes it well suited to a non-persistent CGI scenario.

METHODS

Here are the methods used to process the forms and cookies:

new

The constructor takes no arguments and returns a new CGI::Lite object.

parse_form_data

This handles the following types of requests: GET, HEAD and POST. By default, CGI::Lite uses the environment variable REQUEST_METHOD to determine the manner in which the query/form information should be decoded. However, it may also be passed a valid request method as a scalar string to force CGI::Lite to decode the information in a specific manner.

my $params = $cgi->parse_form_data ('GET');

For multipart/form-data, uploaded files are stored in the user selected directory (see set_directory). If timestamp mode is on (see add_timestamp), the files are named in the following format:

timestamp__filename

where the filename is specified in the "Content-disposition" header. NOTE:, the browser URL encodes the name of the file. This module makes no effort to decode the information for security reasons. However, this can be achieved by creating a subroutine and then using the filter_filename method.

Returns either a hash or a reference to the hash, which contains all of the key/value pairs. For fields that contain file information, the value contains either the path to the file, or the filehandle (see the set_file_type method).

parse_new_form_data

As for parse_form_data, but clears the CGI object state before processing the request. This is useful in persistent applications (e.g. FCGI), where the CGI object is reused for multiple requests. e.g.

my $CGI = CGI::Lite->new ();
while (FCGI::accept > 0)
{
    my $query = $CGI->parse_new_form_data ();
    # process query
}

parse_cookies

Decodes and parses cookies passed by the browser. This method works in much the same manner as parse_form_data. As these two data sources are treated the same internally, users who wish to extract form and cookie data separately might find it easiest to call parse_cookies first and then parse_new_form_data in order to retrieve two distinct hashes (or hashrefs).

is_error

This method is used to check for any potential errors after calling either parse_form_data or parse_cookies.

my $form = $cgi->parse_form_data ();
my $went_wrong = $cgi->is_error ();

Returns 0 if there is no error, 1 otherwise.

get_error_message

If an error occurs when parsing form/query information or cookies, this method may be used to retrieve the error message. Remember, the presence of any errors can be checked by calling the is_error method.

my $msg = $cgi->get_error_message ();

Returns the error message as a plain text string.

set_platform

This method is used to set the platform on which the web server is running. CGI::Lite uses this information to translate end-of-line (EOL) characters for uploaded files (see the add_mime_type and remove_mime_type methods) so that they are accounted for properly on that platform.

$cgi->set_platform ($platform);

$platform can be any of (case insensitive):

Unix                                  EOL: \012      = \n
Windows, Windows95, DOS, NT, PC       EOL: \015\012  = \r\n
Mac or Macintosh                      EOL: \015      = \r

"Unix" is the default.

Returns undef.

set_size_limit

To set a specific limit on the total size of the request (in bytes) call this method with that size as the sole argument. A size of zero effectively disables POST requests. To specify an unlimited size (the default) use an argument of -1.

my $size_limit = $cgi->set_size_limit (10_000_000);

Returns the new value if provided, otherwise the existing value.

deny_uploads

To prevent any file uploads simply call this method with an argument of 1. To enable them again, use an argument of zero.

my $deny_uploads = $cgi->deny_uploads (1);

Returns the new value if provided, otherwise the existing value.

force_unique_cookies

It is generally considered a mistake to send an HTTP request with multiple cookies of the same name. However, the RFC is somewhat vague regarding how servers are expected to handle such an eventuality. CGI::Lite has always allowed such multiple values and returned them as an arrayref to be entirely consistent with the same treatment of form/query data.

To override the default behaviour this method may be called with a single integer argument before the call to parse_cookies. An argument of 1 means that the first cookie value will be used and the others discarded. An argument of 2 means that the last cookie value will be used and the others discarded. An argument of 3 means that an arrayref will be returned as usual but an error raised to indicate the situation. An argument of 0 (or any other value) sets it back to the default.

$cgi->force_unique_cookies (1);
$cgi->parse_cookies;

Note that if there is already an item of data in the CGI::Lite object which matches the name of a cookie then the subsequent parse_cookies call will treat the new cookie value as another data item and the resulting behaviour will be affected by this method. This is another reason to call parse_cookies before parse_form_data.

Returns the new value if provided, otherwise the existing value.

set_directory

Used to set the directory where the uploaded files will be stored (only applies to the multipart/form-data encoding scheme).

my $tmpdir = '/some/dir';
$cgi->set_directory ($tmpdir) or
    die "Directory $tmpdir cannot be used.\n";

This function should be called before parse_form_data, or else the directory defaults to "/tmp". If the application cannot write to the directory for whatever reason, an error status is returned.

Returns 0 on error, 1 otherwise.

close_all_files

$cgi->close_all_files;

All uploaded files that are opened as a result of calling set_file_type with the "handle" argument can be closed in one shot by calling this method which takes no arguments and returns undef.

add_mime_type

By default, EOL characters are translated for all uploaded files with specific MIME types (i.e. text/plain, text/html, etc.). This method can be used to add to the list of MIME types. For example, if you want CGI::Lite to translate EOL characters for uploaded files of application/mac-binhex40, then you would do this:

$cgi->add_mime_type ('application/mac-binhex40');

Returns 1 if this MIME type is newly added, 0 otherwise.

remove_mime_type

This method is the converse of add_mime_type. It allows for the removal of a particular MIME type. For example, if you do not want CGI::Lite to translate EOL characters for uploaded files of type text/html, then you would do this:

$cgi->remove_mime_type ('text/html');

Returns 1 if this MIME type is newly deleted, 0 otherwise.

get_mime_types

Returns the list of the MIME types for which EOL translation is performed.

my @mimelist = $cgi->get_mime_types ();

get_upload_type

Returns the MIME type of uploaded data. Takes the field name as a scalar argument. This previously undocumented function was named print_mime_type prior to version 3.0.

my $this_type = $cgi->get_upload_type ($field);

Returns the MIME type as a scalar string if single valued, an arrayref if multi-valued or undef if the argument does not exist or has no type.

set_file_type

The names of uploaded files are returned by default when the parse_form_data method is called . But if this method is passed the string "handle" as its argument beforehand then the handles to the files are returned instead. However, the name of each handle still corresponds to the filename.

# $fh has been set to one of 'handle' or 'file'
$cgi->set_file_type ($fh);

This function should be called before any call to parse_form_data, or else it will have no effect.

add_timestamp

By default, a timestamp is added to the front of uploaded files. However, there is the option of completely turning off timestamp mode (value 0), or adding a timestamp only for existing files (value 2).

$cgi->add_timestamp ($tsflag);	
# where $tsflag takes one of these values
#       0 = no timestamp
#       1 = timestamp all files (default)
#       2 = timestamp only if file exists

filter_filename

This method is used to change the manner in which uploaded files are named. For example, if you want uploaded filenames to be all upper case, you can use the following code:

$cgi->filter_filename (\&make_uppercase);
$cgi->parse_form_data;

# ...

sub make_uppercase
{
    my $file = shift;

    $file =~ tr/a-z/A-Z/;
    return $file;
}

This method is perhaps best used to sanitise filenames for a specific O/S or filesystem e.g. by removing spaces or leading hyphens, etc.

set_buffer_size

This method allows fine-grained control of the buffer size used internally when dealing with multipart form data. However, the actual buffer size that the algorithm uses can be up to 3x the value specified as the argument. This ensures that boundary strings are not "split" between multiple reads. So, take this into consideration when setting the buffer size.

my $size = $cgi->set_buffer_size (4096);

The buffer size may not be set below 256 bytes nor above the total amount of multipart form data. The default value is 1024 bytes.

Returns the buffer size.

get_ordered_keys

Returns either a reference to an array or an array itself consisting of the form fields/cookies in the order they were parsed.

my $keys = $cgi->get_ordered_keys;
my @keys = $cgi->get_ordered_keys;

print_data

Displays all the key/value pairs (either form data or cookie information) in an ordered fashion to standard output. It is mainly useful for debugging. There are no arguments and no return values.

wrap_textarea

This is a method to wrap a long string into one that is separated by EOL characters (see set_platform) at fixed lengths. The two arguments to be passed to this method are the string and the length at which the line separator is to be added.

my $new_string = $cgi->wrap_textarea ($string, $length);

Returns the modified string.

get_multiple_values

The values returned by the parsing methods in this module for multiple fields with the same name are given as array references. This utility method exists to convert either a scalar value or an array reference into a list thus removing the need for the user to determine whether the returned value for any field is a reference or a scalar.

@all_values = $cgi->get_multiple_values ($reference);

It is only provided as a convenience to the user and is not used internally by the module itself.

Returns a list consisting of the multiple values.

browser_escape

Certain characters have special significance within HTML. These characters are: <, >, &, ", # and %. To display these "special" characters, they can be escaped using the following notation "&#NNN;" where NNN is their ASCII code. This utility method does just that.

$escaped_string = $cgi->browser_escape ($string);

Returns the escaped string.

url_encode

This method will URL-encode a string passed as its argument. It may be used to encode any data to be passed as a query string to a CGI application, for example.

$encoded_string = $cgi->url_encode ($string);

Returns the URL-encoded string.

url_decode

This method is used to URL-decode a string.

$decoded_string = $cgi->url_decode ($string);

Returns the URL-decoded string.

is_dangerous

This method checks for the existence of dangerous meta-characters.

$status = $cgi->is_dangerous ($string);

Returns 1 if such characters are found, 0 otherwise.

DEPRECATED METHODS

The following methods and subroutines are deprecated. Please do not use them in new code and consider excising them from old code. They will be removed in a future release.

return_error

$cgi->return_error ('error 1', 'error 2', 'error 3');

You can use this method to print errors to standard output (ie. as part of the HTTP response) and exit. This method is deprecated as of version 3.0. The same functionality can be achieved with:

print ('error 1', 'error 2', 'error 3');
exit 1;

create_variables

This method is deprecated as of version 3.0. It runs contrary to the principles of structured programming and has really nothing to do with CGI form or cookie handling. It is retained here for backwards compatibility but will be removed entirely in later versions.

%form = ('name'   => 'alan wells',
         'sport'  => 'track and field',
         'events' => '100m');

$cgi->create_variables (\%hash);

This converts a hash ref into scalars named for its keys and this example will create three scalar variables: $name, $sport and $events.

OBSOLETE METHODS/SUBROUTINES

The following methods and subroutines were deprecated in the 2.x branch and have now been removed entirely from the module.

escape_dangerous_chars: The use of this subroutine had been strongly discouraged for more than a decade (See https://web.archive.org/web/20100627014535/http://use.perl.org/~cbrooks/journal/10542 and http://www.securityfocus.com/archive/1/311414 for an advisory by Ronald F. Guilmette.) It has been removed as of version 3.0.
print_form_data: Use print_data instead.
print_cookie_data: Use print_data instead.

Compatibility note: in 2.x and older versions the following were to be used as subroutines rather than methods:

browser_escape
url_encode
url_decode
is_dangerous

They will still work as such and are still exported by default. Users are encouraged to migrate to the new method calls instead as both the export and subroutine interface will be retired in future. Non-method use currently triggers a warning.

VERSIONS

This module maintained backwards compatibility with versions of Perl back to 5.002 for a very long time. Such stability is a welcome attribute but it restricts the code by disallowing access to features introduced into the language since 1996.

With this in mind, there are two maintained branches of this module going forwards. The 2.x branch will retain the backwards compatibility but will not have any new features introduced. Changes to this legacy branch will be bug fixes only. The new 3.x branch will be the main release and will require a more modern perl (5.6.0 is now the bare minimum). The 3.x branch has new features and has removed some of the legacy code including some methods which had been deprecated for more than a decade. The attention of users wishing to upgrade from 2.x to 3.x is drawn to the "DEPRECATED METHODS" and "OBSOLETE METHODS/SUBROUTINES" sections of this document.

Requests for new features in the 3.x branch should be made via the request tracker at https://rt.cpan.org/Public/Dist/Display.html?Name=CGI-Lite

REPOSITORY

https://gitlab.com/openstrike/cgi-lite/

MAINTAINER

Maintenance of this module as of May 2014 has been taken over by Pete Houston <cpan@openstrike.co.uk>.

ACKNOWLEDGMENTS

The author (Shishir) thanks the following for finding bugs and offering suggestions:

Eric D. Friedman
Thomas Winzig
Len Charest
Achim Bohnet
John E. Townsend
Andrew McRae
Dennis Grant
Scott Neufeld
Raul Almquist
and many others!

The present maintainer wishes to thank the previous maintainers: Smylers, Andreas, Ben and Shishir.

COPYRIGHT INFORMATION

Permission to use, copy, and distribute is hereby granted, providing that the above copyright notice and this permission appear in all copies and in supporting documentation.

LICENCE

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

To install CGI::Lite, copy and paste the appropriate command in to your terminal.

cpanm

cpanm CGI::Lite

CPAN shell

perl -MCPAN -e shell
install CGI::Lite

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS

new

parse_form_data

parse_new_form_data

parse_cookies

is_error

get_error_message

set_platform

set_size_limit

deny_uploads

force_unique_cookies

set_directory

close_all_files

add_mime_type

remove_mime_type

get_mime_types

get_upload_type

set_file_type

add_timestamp

filter_filename

set_buffer_size

get_ordered_keys

print_data

wrap_textarea

get_multiple_values

browser_escape

url_encode

url_decode

is_dangerous

DEPRECATED METHODS

OBSOLETE METHODS/SUBROUTINES

VERSIONS

SEE ALSO

REPOSITORY

MAINTAINER

ACKNOWLEDGMENTS

COPYRIGHT INFORMATION

LICENCE

Module Install Instructions