| CGI::Simple::Cookie - Interface to Netscape Cookies |
CGI::Simple::Cookie - Interface to Netscape Cookies
use CGI::Simple::Standard qw(header);
use CGI::Simple::Cookie;
# Create new cookies and send them
$cookie1 = new CGI::Simple::Cookie( -name=>'ID', -value=>123456 );
$cookie2 = new CGI::Simple::Cookie( -name=>'preferences',
-value=>{ font => Helvetica,
size => 12 }
);
print header( -cookie=>[$cookie1,$cookie2] );
# fetch existing cookies
%cookies = fetch CGI::Simple::Cookie;
$id = $cookies{'ID'}->value;
# create cookies returned from an external source
%cookies = parse CGI::Simple::Cookie($ENV{COOKIE});
CGI::Simple::Cookie is an interface to Netscape (HTTP/1.1) cookies, an innovation that allows Web servers to store persistent information on the browser's side of the connection. Although CGI::Simple::Cookie is intended to be used in conjunction with CGI::Simple.pm (and is in fact used by it internally), you can use this module independently.
For full information on cookies see:
http://www.ics.uci.edu/pub/ietf/http/rfc2109.txt
CGI::Simple::Cookie is object oriented. Each cookie object has a name and a value. The name is any scalar value. The value is any scalar or array value (associative arrays are also allowed). Cookies also have several optional attributes, including:
$c = new CGI::Simple::Cookie( -name => 'foo',
-value => 'bar',
-expires => '+3M',
-domain => '.capricorn.com',
-path => '/cgi-bin/database',
-secure => 1
);
Create cookies from scratch with the new method. The -name and -value parameters are required. The name must be a scalar value. The value can be a scalar, an array reference, or a hash reference. (At some point in the future cookies will support one of the Perl object serialization protocols for full generality).
-expires accepts any of the relative or absolute date formats recognized by CGI::Simple.pm, for example ``+3M'' for three months in the future. See CGI::Simple.pm's documentation for details.
-domain points to a domain name or to a fully qualified host name. If not specified, the cookie will be returned only to the Web server that created it.
-path points to a partial URL on the current server. The cookie will be returned to all URLs beginning with the specified path. If not specified, it defaults to '/', which returns the cookie to all pages at your site.
-secure if set to a true value instructs the browser to return the cookie only when a cryptographic protocol is in use.
Within a CGI script you can send a cookie to the browser by creating one or more Set-Cookie: fields in the HTTP header. Here is a typical sequence:
$c = new CGI::Simple::Cookie( -name => 'foo',
-value => ['bar','baz'],
-expires => '+3M'
);
print "Set-Cookie: $c\n";
print "Content-Type: text/html\n\n";
To send more than one cookie, create several Set-Cookie: fields. Alternatively, you may concatenate the cookies together with ``; '' and send them in one field.
If you are using CGI::Simple.pm, you send cookies by providing a -cookie
argument to the header() method:
print header( -cookie=>$c );
Mod_perl users can set cookies using the request object's header_out()
method:
$r->header_out('Set-Cookie',$c);
Internally, Cookie overloads the ``'' operator to call its as_string()
method when incorporated into the HTTP header. as_string() turns the
Cookie's internal representation into an RFC-compliant text
representation. You may call as_string() yourself if you prefer:
print "Set-Cookie: ",$c->as_string,"\n";
%cookies = fetch CGI::Simple::Cookie;
fetch returns an associative array consisting of all cookies returned by the browser. The keys of the array are the cookie names. You can iterate through the cookies this way:
%cookies = fetch CGI::Simple::Cookie;
foreach (keys %cookies) {
do_something($cookies{$_});
}
In a scalar context, fetch() returns a hash reference, which may be more
efficient if you are manipulating multiple cookies.
CGI::Simple.pm uses the URL escaping methods to save and restore reserved
characters in its cookies. If you are trying to retrieve a cookie set by
a foreign server, this escaping method may trip you up. Use raw_fetch()
instead, which has the same semantics as fetch(), but performs no unescaping.
You may also retrieve cookies that were stored in some external
form using the parse() class method:
$COOKIES = `cat /usr/tmp/Cookie_stash`;
%cookies = parse CGI::Simple::Cookie($COOKIES);
Cookie objects have a series of accessor methods to get and set cookie attributes. Each accessor has a similar syntax. Called without arguments, the accessor returns the current value of the attribute. Called with an argument, the accessor changes the attribute and returns its new value.
$name = $c->name;
$new_name = $c->name('fred');
$value = $c->value;
@new_value = $c->value(['a','b','c','d']);
value() is context sensitive. In a list context it will return the current value of the cookie as an array. In a scalar context it will return the first value of a multivalued cookie.
Original version copyright 1997-1998, Lincoln D. Stein. All rights reserved. Originally copyright 2001 Dr James Freeman <jfreeman@tassie.net.au> This release by Andy Armstrong <andy@hexten.net>
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Address bug reports and comments to: andy@hexten.net
This section intentionally left blank :-)
the CGI::Carp manpage, the CGI::Simple manpage
| CGI::Simple::Cookie - Interface to Netscape Cookies |