Perl Cd Bookshelf [Electronic resources]

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.

$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.

$c->as_string

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

$c->domain(val)

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

$c->expires(val)

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

%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.

$c->name(val)

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

%cookies = parse CGI::Cookie(stored_cookies)

Retrieves cookies stored in an external form.

$c->path(val)

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

%cookies = raw_fetch CGI::Cookie

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

$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.