Apache::Cookie

A class for manipulating a request's HTTP cookies. This functionality is only available if mod_ruby is compiled with Generic Apache Request library (libapreq) support. A hash of the cookies associated with a request can be fetched by calling Apache::Request#cookies?.

Object

DateFormat

The strftime-compatible date format used in the #expires? attribute for absolute expirations.

new( request, [options] )

Returns a new Apache::Cookie for the specified request (an Apache::Request object). The optional options Hash may be used to initialize the cookie's attributes. The following keys are supported:

:name

Sets the name field to the given value.

:value

Adds the value to the values field.

:expires

Sets the expires field to the calculated date String or Time object. See Apache::Cookie#expires? for a listing of format options. The default is nil.

:domain

Sets the domain field to the given value. The default is nil.

:path

Sets the path field to the given value. The default path is derived from the requested uri.

:secure

Sets the secure field to true or false.

bake

Add the cookie to the output headers of the request to which it belongs.

domain

domain=

Get/set the domain attribute of the cookie. From the Netscape spec:

When searching the cookie list for valid cookies, a comparison of the
(({domain})) attributes of the cookie is made with the Internet domain
name of the host from which the URL will be fetched. If there is a tail
match, then the cookie will go through path matching to see if it should
be sent. "Tail matching" means that (({domain})) attribute is matched
against the tail of the fully qualified domain name of the host. A
(({domain})) attribute of "acme.com" would match host names
"anvil.acme.com" as well as "shipping.crate.acme.com".

Only hosts within the specified domain can set a cookie for a domain and
domains must have at least two (2) or three (3) periods in them to
prevent domains of the form: ".com", ".edu", and "va.us". Any domain
that fails within one of the seven special top level domains listed
below only require two periods. Any other domain requires at least
three. The seven special top level domains are: "COM", "EDU", "NET",
"ORG", "GOV", "MIL", and "INT".

The default value of (({domain})) is the host name of the server which
generated the cookie response.

expires

expires=

Sets the expires field. The value can be either a Time object or a String in any of the following formats:

+30s

30 seconds from now

+10m

ten minutes from now

+1h

one hour from now

-1d

yesterday (i.e. "ASAP!")

now

immediately

+3M

in three months

+10y

in ten years time

Thursday, 25-Apr-1999 00:40:33 GMT

at the indicated time & date

name

name=

Get/set the name associated with the cookie.

path

path=

Get/set the cookie's path attribute. From the Netscape spec:

The (({path})) attribute is used to specify the subset of URLs in a
domain for which the cookie is valid. If a cookie has already passed
(({domain})) matching, then the pathname component of the URL is
compared with the path attribute, and if there is a match, the cookie is
considered valid and is sent along with the URL request. The path "/foo"
would match "/foobar" and "/foo/bar.html". The path "/" is the most
general path.

If the (({path})) is not specified, it as assumed to be the same path as
the document being described by the header which contains the cookie.

secure=

Set the cookie's secure flag to the given value.

secure?

Returns true if the cookie's secure flag is set.

to_s

Returns the cookie as a String.

value

Get the first value stored in the cookie as a String.

values

Get all the values stored in the cookie as an Array.

value=

Set the value of the cookie. If the new value responds to #each, #each will be called, and the result of calling #to_s on each iterated value will be added to the cookie's value. If the new value doesn't respond to #each, the result of calling #to_s on the value itself is added.

For example:

svarcookie = Apache::Cookie::new( req, :name => 'sessionvars' )
svarcookie.value = [ Time::now, req.headers_in['host'] ]
svarcookie.bake