The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
CGI-Easy-v2.0.1
River stage one • 1 direct dependent • 1 total dependent
1 ++
/ CGI::Easy::Request

NAME

CGI::Easy::Request - parse CGI params

VERSION

This document describes CGI::Easy::Request version v2.0.1

SYNOPSIS

    use CGI::Easy::Request;

    my $r = CGI::Easy::Request->new();
    my $r = CGI::Easy::Request->new({
        frontend_prefix     => 'X-Real-',
        max_post            => 10*1024*1024,
        post_with_get       => 1,
        raw                 => 1,
        keep_all_values     => 1,
    });

    if ($r->{error}) {  # incorrect HTTP request
        print "417 Expectation Failed\r\n\r\n";
        print $r->{error};
        exit;
    }

    my @all_param_names = $r->param();
    my $myparam = $r->param('myparam'); # first 'myparam' value
    my @myparam = $r->param('myparam'); # all 'myparam' values

    print $r->{GET}{'myarray[]'}[0];
    print $r->{GET}{myparam};       # without keep_all_values=>1
    print $r->{GET}{myparam}[0];    # with keep_all_values=>1

    $uploaded_file      = $r->{POST}{myfile};
    $uploaded_filename  = $r->{filename}{myfile};

    print $r->{cookie}{mycookie};

    print $r->{ENV}{HTTP_USER_AGENT};

DESCRIPTION

Parse CGI params (from %ENV and STDIN) and provide user with ease to use hash (object) with all interesting data.

FEATURES

  • DoS protection

    Maximum size of content in STDIN is always limited.

  • HTTP Basic authorization support

    Provide CGI with remote user name and password.

  • UTF8 support

    Decode path, GET/POST/cookie names and values (except uploaded files content) and uploaded file names from UTF8 to Unicode.

  • Frontend web server support

    Can take REMOTE_ADDR/REMOTE_PORT and "https" scheme from non-standard HTTP headers (like X-Real-REMOTE-ADDR) which is usually set by nginx/lighttpd frontends.

  • HEAD/GET/POST/PUT/DELETE/… support

    Params sent with POST or PUT method will be placed in {POST}, params for all other methods (including unknown) will be placed in {GET}.

INTERFACE

new

    $r = CGI::Easy::Request->new();
    $r = CGI::Easy::Request->new( \%opt );

Parse CGI request from %ENV and STDIN.

Create new object, which contain all parsed data in public fields. You can access/modify all fields of this object in any way.

If given, %opt may contain these fields:

{frontend_prefix}

If there frontend web server used, then CGI executed on backend web server will not be able to detect user's IP/port and is HTTPS used in usual way, because CGI "user" now isn't real user, but frontend web server instead.

In this case usual environment variables REMOTE_ADDR and REMOTE_PORT will contain frontend web server's address, and variable HTTPS will not exists (because frontend will not use https to connect to backend even if user connects to frontend using https).

Frontend can be configured to send real user's IP/port/https in custom HTTP headers (like X-Real-REMOTE_ADDR, X-Real-REMOTE_PORT, X-Real-HTTPS). For example, nginx configuration may looks like:

    server {
        listen *:80;
        ...
        proxy_set_header    X-Real-REMOTE_ADDR      $remote_addr;
        proxy_set_header    X-Real-REMOTE_PORT      $remote_port;
        proxy_set_header    X-Real-HTTPS            "";
    }
    server {
        listen *:443;
        ...
        proxy_set_header    X-Real-REMOTE_ADDR      $remote_addr;
        proxy_set_header    X-Real-REMOTE_PORT      $remote_port;
        proxy_set_header    X-Real-HTTPS            on;
    }

If you can guarantee only frontend is able to connect to backend, then you can safely trust these X-Real-* headers. In this case you can set frontend_prefix => 'X-Real-' and new() will parse headers with this prefix instead of standard REMOTE_ADDR, REMOTE_PORT and HTTPS variables.

{max_post}

To protect against DoS attack, size of POST/PUT request is always limited. Default limit is 1 MB. You can change it using {max_post} option (value in bytes).

{post_with_get}

Sometimes POST/PUT request sent to url which also contain some parameters (after '?'). By default these parameters will be ignored, and only parameters sent in HTTP request body (STDIN) will be parsed (to {POST}). If you want to additionally parse parameters from url you should set post_with_get => 1 option (these parameters will be parsed to {GET} and not mixed with parameters in {POST}).

{keep_all_values}

By default only parameters which names ending with '[]' are allowed to have more than one value. These parameters stored in fields {GET}, {POST}, {filename} and {mimetype} as ARRAYREF, while all other parameters stored as SCALAR (only first value for these parameters is stored). If you want to allow more than one value in all parameters you should set keep_all_values => 1 option, and all parameters will be stored as ARRAYREF.

{raw}

By default we suppose request send either in UTF8 (or ASCII) encoding. Request path, GET/POST/cookie names and values (except uploaded files content) and uploaded file names will be decoded from UTF8 to Unicode.

If you need to handle requests in other encodings, you should disable automatic decoding from UTF8 using raw => 1 option and decode all these things manually.

Created object will contain these fields:

{scheme}

'http' or 'https'.

You may need to use frontend_prefix option if you've frontend and backend web servers to reliably detect 'https' scheme.

{host}
{port}

Host name and port for requested url.

{path}

Path from url, always begin with '/'.

Will be decoded from UTF8 to Unicode unless new() called with option raw=>1.

{GET}
{POST}

Will contain request parameters. For request methods POST and PUT parameters will be stored in {POST} (if option post_with_get => 1 used then parameters from url will be additionally stored in {GET), for all other methods (HEAD/GET/DELETE/etc.) parameters will be stored in {GET}.

These fields will contain HASHREF with parameter names, which value will depend on keep_all_values option. By default, value for parameters which names ending with '[]' will be ARRAYREF, and for all other SCALAR (only first value for these parameters will be stored if more than one available).

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 raw=>1.

{filename}
{mimetype}

When <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 {filename} and {mimetype}, which have same format as {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 raw=>1.

{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 raw=>1.

{REMOTE_ADDR}
{REMOTE_PORT}

User's IP and port.

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

{AUTH_TYPE}
{REMOTE_USER}
{REMOTE_PASS}

There two ways to use HTTP authentication:

1) Web server will check user login/pass, and will provide values for {AUTH_TYPE} and {REMOTE_USER}. In this case {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 {AUTH_TYPE} will be set to 'Basic', and {REMOTE_USER} and {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 .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>
{ENV}
{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.

{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

Return created CGI::Easy::Request object.

param

    @all_param_names = $r->param();
    $first_value = $r->param( $name );
    @all_values  = $r->param( $name );

This method shouldn't be called if you modified format of {GET} or {POST} fields.

When called without parameter will return ARRAY with all CGI parameter names, both GET and POST parameter names will be joined.

When called with parameter name will return value of this parameter (from POST parameter if it exists, or from GET if it doesn't exist in POST parameters). All stored values (see keep_all_values option) for this parameter will be returned in ARRAY context, and only first value will be returned in SCALAR context.

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/powerman/perl-CGI-Easy/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license. Feel free to fork the repository and submit pull requests.

https://github.com/powerman/perl-CGI-Easy

    git clone https://github.com/powerman/perl-CGI-Easy.git

Resources

AUTHOR

Alex Efros <powerman@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2009- by Alex Efros <powerman@cpan.org>.

This is free software, licensed under:

  The MIT (X11) License