view release on metacpan or  search on metacpan

lib/CGI.pod  view on Meta::CPAN

=over 4

=item B<$CGI::POST_MAX>

If set to a non-negative integer, this variable puts a ceiling on the size of
POSTings, in bytes. If CGI.pm detects a POST that is greater than the ceiling,
it will immediately exit with an error message. This value will affect both
ordinary POSTs and multipart POSTs, meaning that it limits the maximum size of
file uploads as well. You should set this to a reasonably high
value, such as 10 megabytes.

=item B<$CGI::DISABLE_UPLOADS>

If set to a non-zero value, this will disable file uploads completely. Other
fill-out form values will work as usual.

=back

To use these variables, set the variable at the top of the script, right after
the "use" statement:

    #!/usr/bin/env perl

    use strict;
    use warnings;

    use CGI;

    $CGI::POST_MAX = 1024 * 1024 * 10;  # max 10MB posts
    $CGI::DISABLE_UPLOADS = 1;          # no uploads

An attempt to send a POST larger than $POST_MAX bytes will cause I<param()> to
return an empty CGI parameter list. You can test for this event by checking
I<cgi_error()>, either after you create the CGI object or, if you are using the
function-oriented interface, call <param()> for the first time. If the POST was
intercepted, then cgi_error() will return the message "413 POST too large".

This error message is actually defined by the HTTP protocol, and is designed to
be returned to the browser as the CGI script's status code. For example:

    my $uploaded_file = $q->param('upload');
    if ( !$uploaded_file && $q->cgi_error() ) {
        print $q->header( -status => $q->cgi_error() );
        exit 0;
   }

However it isn't clear that any browser currently knows what to do with this
status code. It might be better just to create a page that warns the user of
the problem.

=head1 MODULE FLAGS

There are a number of global module flags which affect how CGI.pm operates.

=over 4

=item B<$CGI::APPEND_QUERY_STRING>

If set to a non-zero value, this will add query string parameters to a POST
forms parameters hence allowing I<param()> to return values from the query
string as well as from the decoded POST request instead of having to use
I<url_param> instead. This makes it easier to get the value of a parameter
when you don't know the source.

=back

=head1 COMPATIBILITY WITH CGI-LIB.PL

To make it easier to port existing programs that use cgi-lib.pl the
compatibility routine "ReadParse" is provided. Porting is simple:

OLD VERSION

    require "cgi-lib.pl";
    &ReadParse;
    print "The value of the antique is $in{antique}.\n";

NEW VERSION

    use CGI;
    CGI::ReadParse();
    print "The value of the antique is $in{antique}.\n";

CGI.pm's ReadParse() routine creates a tied variable named %in, which can be
accessed to obtain the query variables. Like ReadParse, you can also provide
your own variable. Infrequently used features of ReadParse, such as the creation
of @in and $in variables, are not supported.

Once you use ReadParse, you can retrieve the query object itself this way:

    my $q = $in{CGI};

This allows you to start using the more interesting features of CGI.pm without
rewriting your old scripts from scratch.

An even simpler way to mix cgi-lib calls with CGI.pm calls is to import both the
C<:cgi-lib> and C<:standard> method:

    use CGI qw(:cgi-lib :standard);
    &ReadParse;
    print "The price of your purchase is $in{price}.\n";
    print textfield(-name=>'price', -default=>'$1.99');

=head2 Cgi-lib functions that are available in CGI.pm

In compatibility mode, the following cgi-lib.pl functions are
available for your use:

    ReadParse()
    PrintHeader()
    SplitParam()
    MethGet()
    MethPost()

=head1 LICENSE

The CGI.pm distribution is copyright 1995-2007, Lincoln D. Stein. It is
distributed under the Artistic License 2.0. It is currently maintained
by Lee Johnson (LEEJO) with help from many contributors.

=head1 CREDITS