• ExSite Cookie Management

• Cookie Scope
• Long-Duration Cookies
• Internals

ExSite Cookie Management

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

Cookie Scope

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;

Long-Duration Cookies

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

Internals

The cookie object has the following internal attributes:

path

The path for which this cookie jar is valid.

domain

The domain for which this cookie jar is valid.

duration

Long-duration cookies will last this long. The duration is specified as a string of the format ``NUMBER TIME_UNITS'', eg. ``7 days'', or ``2 weeks'', or ``3 months''.

jar

A hash of cookie names/values in this cookie jar.