ExSite::Cookie manages your cookie jar, which is a hash (%cookie)
of your cookie names => cookie values. For simple cookie operations,
you simply need to set/unset cookie values in %cookie, and ExSite
will take care of managing the HTTP cookie protocol to preserve these
values throughout your session.
%cookie should automatically be populated with all cookie names
and values on start-up. To check the value of a cookie, simply
look up the cookie name in %cookie:
if ($cookie{foo} eq "bar") { ... }
To set a cookie named ``foo'' to value ``bar'':
$cookie{foo} = "bar";
If this creates a new cookie name or changes the value of an existing
cookie, then ExSite will automatically issue a set-cookie: header so
the browser will remember this cookie setting on future requests. The
set-cookie header will use automatic expiry, path, and domain
settings. Default behaviour is to expire after the browser is closed,
and to be valid for the default ExSite domain ($config{server}{domain})
and CGIpath ($config{server}{CGIpath}).
To set a cookie with custom expiry, path, and domain settings, do this:
(tied %cookie)->set_cookie($name,$value,$path,$domain,$expiry);
$expiry must be in the accepted date format for cookies.
To obtain a set-cookie header line without actually issuing it, do this:
(tied %cookie)->cookie_header($name,$value,$path,$domain,$expiry);
To unset (clear) a cookie named ``foo'', use one of:
delete $cookie{foo};
$cookie{foo} = undef;
To temporarily set a cookie for this request only, but not for subsequent requests, do this:
(tied %cookie)->store($name,$value); # set
(tied %cookie)->store($name,undef); # unset
This has the effect of altering the contents of %cookie but not
actually issuing any set-cookie headers to preserve that information.
These calls only affect the cookie value in the current program.
If spawning other programs that may revert to the original HTTP_COOKIE
value, you will also want to update HTTP_COOKIE:
(tied %cookie)->store_update($name,$value); # set
(tied %cookie)->store_update($name,undef); # unset
Cookies normally apply to a specific domain and server path. The default cookie jar sets these automatically to:
domain = $config{server}{domain}
path = $config{server}{CGIpath}
Cookies not valid in this scope will not be found in the cookie jar.
Cookies set using normal hash settings (eg. $cookie{foo}="bar";)
will be valid for this scope. However, you can set cookies outside
this scope by using the set_cookie() internal method, described
above.
To create an alternate cookie jar with a different scope, simply declare a new cookie hash, and tie it to this class with the new path and domain:
tie %my_cookie, 'ExSite::Cookie', $path, $domain;
By default, cookies expire when the browser is closed. You can optionally set durable cookies as follows:
(tied %cookie)->store_remember($key,$val);
This will set an explicit expiry time for the cookie. However, you must tell your cookie jar what this duration should be, when you set it up:
tie %cookie, 'ExSite::Cookie', $path, $domain, "2 weeks";
The duration is specified as a string of the format ``NUMBER
TIME_UNITS'', eg. ``7 days'', or ``2 weeks'', or ``3 months''. The default
cookie jar uses the configuration setting
auth.long_cookie_duration, which defaults to ``2 weeks''. If you do
not provide your cookie jar with a duration, the cookies will not have
an extended duration. However, you can always pass an explicit expiry
date:
(tied %cookie)->store_remember($key,$val,$expiry);
To get a date string in the correct format for $expiry, use a Time
object. For example:
my $t = new ExSite::Time; # now
$t->add(2,"weeks"); # 2 weeks in future
my $expiry = $t->write("cookie"); # a date string in cookie format
The cookie object has the following internal attributes: