view release on metacpan or  search on metacpan

lib/CGI/Easy/Request.pm  view on Meta::CPAN

Example: request "GET http://example.com/some.cgi?a=5&a=6&b[]=7&b[]=8&c=9"
will be parsed to

    # by default:
    GET => {
        'a'     => 5,
        'b[]'   => [ 7, 8 ],
        'c'     => 9,
    },
    POST => {}

    # with option keep_all_values=>1:
    GET => {
        'a'     => [ 5, 6 ],
        'b[]'   => [ 7, 8 ],
        'c'     => [ 9 ],
    },
    POST => {}

Parameter names and values (except file content) be decoded from UTF8 to
Unicode unless new() called with option C<< raw=>1 >>.

=item {filename}

=item {mimetype}

When C<< <INPUT TYPE="FILE"> >> used to upload files, browser will send
uploaded file name and MIME type in addition to file contents.
These values will be available in fields C<< {filename} >> and C<< {mimetype} >>,
which have same format as C<< {POST} >> field.

Example: submitted form contain parameter "a" with value "5" and parameter
"image" with value of file "C:\Images\some.gif" will be parsed to:

    GET => {},
    POST => {
        a       => 5,
        image   => '...binary image data...',
    },
    filename => {
        a       => undef,
        image   => 'C:\Images\some.gif',
    }
    mimetype => {
        a       => undef,
        image   => 'image/gif',
    }

Parameter names and file names will be decoded from UTF8 to Unicode unless
new() called with option C<< raw=>1 >>.

=item {cookie}

Will contain hash with cookie names and values. Example:

    cookie => {
        some_cookie     => 'some value',
        other_cookie    => 'other value',
    }

Cookie names and values will be decoded from UTF8 to Unicode unless
new() called with option C<< raw=>1 >>.

=item {REMOTE_ADDR}

=item {REMOTE_PORT}

User's IP and port.

You may need to use C<< frontend_prefix >> option if you've frontend and
backend web servers.

=item {AUTH_TYPE}

=item {REMOTE_USER}

=item {REMOTE_PASS}

There two ways to use HTTP authentication:

1) Web server will check user login/pass, and will provide values for
C<< {AUTH_TYPE} >> and C<< {REMOTE_USER} >>. In this case C<< {REMOTE_PASS} >>
will contain undef().

2) Your CGI will manually check authentication. Only 'Basic' type of HTTP
authentication supported by this module. In this case C<< {AUTH_TYPE} >> will be
set to 'Basic', and C<< {REMOTE_USER} >> and C<< {REMOTE_PASS} >> will contain
login/pass sent by user, and your CGI should check is they correct.
To allow this type of manual authentication you may need to configure
C<.htaccess> to force Apache to send HTTP_AUTHORIZATION environment to your
CGI/FastCGI script:

    <Files "myscript.cgi">
        RewriteEngine On
        RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization},L]
    </Files>

=item {ENV}

=item {STDIN}

These fields will contain copy of %ENV and STDIN contents as they was seen
by new(). This is useful to access values in %ENV which doesn't included in
other fields of this object, and to manually parse non-standard data in STDIN.

=item {error}

This field will contain empty string if HTTP request was formed correctly, or
error message if HTTP request was formed incorrectly. Possible errors are:

    failed to parse HTTP_AUTHORIZATION
    POST body too large
    POST body incomplete

=back

Return created CGI::Easy::Request object.

=head2 param

    @all_param_names = $r->param();