CGI::Cookie (Perl in a Nutshell, 2nd Edition)

8.36. CGI::Cookie

Provides an interface to Netscape (HTTP/1.1) cookies that can be used in conjunction with CGI.pm or independently. To use CGI::Cookie, create a new cookie object with the constructor new. You can then send the cookie to the browser in one of the following ways:

From a CGI script, create a Set-Cookie field in the HTTP header for each cookie you want to send ($c is the cookie object):

print "Set-Cookie: $c0";

With CGI.pm (see Chapter 10, "The CGI.pm Module"), use the header method with a -cookie argument:
```
print header(-cookie=>$c);
```
Using mod_perl (see Chapter 11, "Web Server Programmingwith mod_perl"), use the request object's header_out method:
```
$r->header_out('Set-Cookie',$c);
```
The following methods are provided for CGI::Cookie.

new

$c = new CGI::Cookie(attribs)

Constructor. Creates a new cookie. Attributes are:

-domain = domain_name: Optional. Points to domain name or fully qualified hostname to which cookie will be returned. If missing, browser will return cookie only to the server that set it.
-expires = date: Optional expiration date in any of the date formats recognized by CGI.pm. If missing, cookie expires at the end of this browser session.
-name = name: Required. Scalar value with the cookie name.
-path = path: Optional. Points to a partial URL on the current server; cookies will be returned to any URL beginning with this path. Defaults to /.
-secure = boolean: Optional. If true, browser will return cookie only if a cryptographic protocol is in use.
-value = value: Required. The value of the cookie; can be a scalar, an array reference, or a hash reference.

as_string

$c->as_string

Turns internal representation of cookie into RFC-compliant text. Called internally by overloading the "" operator, or can be called directly.

domain

$c->domain(val)

Gets or sets the cookie's domain. With no parameter, gets the current value; otherwise, sets the new value.

expires

$c->expires(val)

Gets or sets the cookie's expiration date. With no parameter, gets the current expiration date; otherwise, sets the new value.

fetch

%cookies = fetch CGI::Cookie

Returns a hash containing cookies returned by the browser, in which the keys are the cookie names and the values are the cookie values. In a scalar context, fetch returns a hash reference.

name

$c->name(val)

Gets or sets the cookie's name. With no parameter, returns the current name; otherwise, sets the new value.

parse

%cookies = parse CGI::Cookie(stored_cookies)

Retrieves cookies stored in an external form.

path

$c->path(val)

Gets or sets the cookie's path. With no parameter, returns the current path; otherwise, sets the new value.

raw_fetch

%cookies = raw_fetch CGI::Cookie

Like fetch, but does no unescaping of reserved characters; useful for retrieving cookies set by a foreign server.

value

$c->value(val)

Gets or sets the cookie's value. With no parameter, returns the current value; otherwise, sets the new value. In array context, returns the current value as an array. In scalar context, returns the first value of a multivalued cookie.