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_heaader($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.
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;
The cookie object has 3 internal attributes: