Setting Cookies (Perl Cookbook, 2nd Edition)

## 21.2. Setting Cookies

### 21.2.1. Problem

You want to send a cookie to a client as part of a response.

### 21.2.2. Solution

Use the Apache::Cookie module from CPAN. From within your content handler, create a new cookie and attach it to the outgoing headers:

>     use Apache::Cookie;
>     $cookie = Apache::Cookie->new($r,
>                                   -name    => "cookie name",
>                                   -value   => "its value",
>                                   -expires => "+1d" );
>     $cookie->bake;

Don't forget to send the headers before generating content:

>     $r->send_http_header;

>     $r->print("...");

### 21.2.3. Description

The Apache::Cookie module builds a string that represents a cookie. To specify an expiration time for your cookie, use one of these formats:

`+30s` | 30 seconds from now
`+10m` | 10 minutes from now
`+1h` | 1 hour from now
`-1d` | 1 day ago
`now` | Now
`+3M` | Three months from now
`+10y` | Ten years from now
`Thursday, 25-Apr-1999 00:30:31 GMT` | Then

Call the `bake` method once you finish changing the cookie's parameters. This adds the cookie in its current state to mod_perl's planned response. If you change the cookie object after calling `bake`, changes won't be reflected in the header sent by mod_perl.

Apache maintains two sets of headers: error headers (which, confusingly, are always sent, regardless of whether the response code indicates an error) and ordinary headers (which are sent only for successful responses). Apache::Cookie sets the cookie in the error headers, so the cookie will be sent even for redirection responses.

The CGI::Cookie module is a slower pure Perl module with the same interface, which should be used only when the XS module Apache::Cookie is unavailable. To use it, substitute "CGI::Cookie" for "Apache::Cookie" in your code and remove the request object from the call to `new`. You can't call `bake` either—instead you must say:

>     $r->err_headers_out->add("Set-Cookie", $cookie->as_string);

We use `err_headers_out` rather than `err_header_out` because the former method allows for multiple values for a header, whereas the latter does not. That is, `err_headers_out` lets you build up a header over time by adding to its existing value before it's sent, as we might do here if we independently set three cookies. The `err_header_out` method always replaces, never augments.

### 21.2.4. See Also

The documentation for the CGI::Cookie and Apache::Cookie modules on CPAN; the Netscape cookie specification at http://wp.netscape.com/newsref/std/cookie_spec.html; Recipe 3.7 in mod_perl Developer's Cookbook; the Apache.pm manpage

Copyright © 2003 O'Reilly & Associates. All rights reserved.