view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    way:

        my $cookie = $q->cookie(
            -name  => 'family information',
            -value => \%childrens_ages
        );

- **-path**

    The optional partial path for which this cookie will be valid, as described
    above.

- **-domain**

    The optional partial domain for which this cookie will be valid, as described
    above.

- **-expires**

    The optional expiration date for this cookie. The format is as described in the
    section on the **header()** method:

        "+1h"  one hour from now

- **-secure**

    If set to true, this cookie will only be used within a secure SSL session.

The cookie created by cookie() must be incorporated into the HTTP header within
the string returned by the header() method:

    use strict;
    use warnings;

    use CGI;

    my $q      = CGI->new;
    my $cookie = ...
    print $q->header( -cookie => $cookie );

To create multiple cookies, give header() an array reference:

    my $cookie1 = $q->cookie(
        -name  => 'riddle_name',
        -value => "The Sphynx's Question"
    );

    my $cookie2 = $q->cookie(
        -name  => 'answers',
        -value => \%answers
    );

    print $q->header( -cookie => [ $cookie1,$cookie2 ] );

To retrieve a cookie, request it by name by calling cookie() method without the
**-value** parameter. This example uses the object-oriented form:

    my $riddle  = $q->cookie('riddle_name');
    my %answers = $q->cookie('answers');

Cookies created with a single scalar value, such as the "riddle\_name" cookie,
will be returned in that form. Cookies with array and hash values can also be
retrieved.

The cookie and CGI namespaces are separate. If you have a parameter named
'answers' and a cookie named 'answers', the values retrieved by param() and
cookie() are independent of each other. However, it's simple to turn a CGI
parameter into a cookie, and vice-versa:

    # turn a CGI parameter into a cookie
    my $c = cookie( -name => 'answers',-value => [$q->param('answers')] );
    # vice-versa
    $q->param( -name => 'answers',-value => [ $q->cookie('answers')] );

If you call cookie() without any parameters, it will return a list of
the names of all cookies passed to your script:

    my @cookies = $q->cookie();

See the **cookie.cgi** example script for some ideas on how to use cookies
effectively.

- **$CGI::COOKIE\_CACHE**

    If set to a non-negative integer, this variable will cause CGI.pm to use the
    cached cookie details from the previous call to cookie(). By default this
    cache is off to retain backwards compatibility.

# DEBUGGING

If you are running the script from the command line or in the perl debugger,
you can pass the script a list of keywords or parameter=value pairs on the
command line or from standard input (you don't have to worry about tricking
your script into reading from environment variables). You can pass keywords
like this:

    your_script.pl keyword1 keyword2 keyword3

or this:

    your_script.pl keyword1+keyword2+keyword3

or this:

    your_script.pl name1=value1 name2=value2

or this:

    your_script.pl name1=value1&name2=value2

To turn off this feature, use the -no\_debug pragma.

To test the POST method, you may enable full debugging with the -debug pragma.
This will allow you to feed newline-delimited name=value pairs to the script on
standard input.

When debugging, you can use quotes and backslashes to escape characters in the
familiar shell manner, letting you place spaces and other funny characters in
your parameter=value pairs:

    your_script.pl "name1='I am a long value'" "name2=two\ words"

Finally, you can set the path info for the script by prefixing the first
name/value parameter with the path followed by a question mark (?):

    your_script.pl /your/path/here?name1=value1&name2=value2

# FETCHING ENVIRONMENT VARIABLES

Some of the more useful environment variables can be fetched through this
interface. The methods are as follows:

- **Accept()**

    Return a list of MIME types that the remote browser accepts. If you give this
    method a single argument corresponding to a MIME type, as in
    Accept('text/html'), it will return a floating point value corresponding to the
    browser's preference for this type from 0.0 (don't want) to 1.0. Glob types
    (e.g. text/\*) in the browser's accept list are handled correctly.

    Note that the capitalization changed between version 2.43 and 2.44 in order to
    avoid conflict with perl's accept() function.

- **raw\_cookie()**

    Returns the HTTP\_COOKIE variable. Cookies have a special format, and this
    method call just returns the raw form (?cookie dough). See cookie() for ways
    of setting and retrieving cooked cookies.

    Called with no parameters, raw\_cookie() returns the packed cookie structure.
    You can separate it into individual cookies by splitting on the character
    sequence "; ". Called with the name of a cookie, retrieves the **unescaped**
    form of the cookie. You can use the regular cookie() method to get the names,
    or use the raw\_fetch() method from the CGI::Cookie module.

- **env\_query\_string()**

    Returns the QUERY\_STRING variable, note that this is the original value as set
    in the environment by the webserver and (possibly) not the same value as
    returned by query\_string(), which represents the object state

- **user\_agent()**

    Returns the HTTP\_USER\_AGENT variable. If you give this method a single
    argument, it will attempt to pattern match on it, allowing you to do something
    like user\_agent(Mozilla);

- **path\_info()**

    Returns additional path information from the script URL. E.G. fetching
    /cgi-bin/your\_script/additional/stuff will result in path\_info() returning
    "/additional/stuff".

    NOTE: The Microsoft Internet Information Server is broken with respect to
    additional path information. If you use the perl DLL library, the IIS server
    will attempt to execute the additional path information as a perl script. If
    you use the ordinary file associations mapping, the path information will be
    present in the environment, but incorrect. The best thing to do is to avoid
    using additional path information in CGI scripts destined for use with IIS. A
    best attempt has been made to make CGI.pm do the right thing.

- **path\_translated()**

    As per path\_info() but returns the additional path information translated into
    a physical path, e.g. "/usr/local/etc/httpd/htdocs/additional/stuff".

    The Microsoft IIS is broken with respect to the translated path as well.

- **remote\_host()**

    Returns either the remote host name or IP address if the former is unavailable.

- **remote\_ident()**

    Returns the name of the remote user (as returned by identd) or undef if not set

- **remote\_addr()**

    Returns the remote host IP address, or 127.0.0.1 if the address is unavailable.

- **request\_uri()**

    Returns the interpreted pathname of the requested document or CGI (relative to
    the document root). Or undef if not set.

- **script\_name()**

    Return the script name as a partial URL, for self-referring scripts.

- **referer()**

    Return the URL of the page the browser was viewing prior to fetching your
    script.