NAME

Apache::Cookie - HTTP Cookies Class

SYNOPSIS

    use Apache::Cookie ();
    my $r = Apache->request;
    my $cookie = Apache::Cookie->new($r, ...);

DESCRIPTION

The Apache::Cookie module is a Perl interface to the cookie routines in libapreq. The interface is based on Lincoln Stein's CGI::Cookie module.

METHODS

Apache::Cookie does not export any symbols to the caller's namespace. Except for the request object passed to Apache::Cookie::new, the OO interface is identical to CGI::Cookie. Please consult the CGI::Cookie documentation for more details.

new

Just like CGI::Cookie::new, but requires an Apache request object:

        my $cookie = Apache::Cookie->new($r,
                             -name    =>  'foo', 
                             -value   =>  'bar', 
                             -expires =>  '+3M', 
                             -domain  =>  '.capricorn.com', 
                             -path    =>  '/cgi-bin/database',
                             -secure  =>  1 
                            );

bake

Put cookie in the oven to bake. (Add a Set-Cookie header to the outgoing headers table.)

    $cookie->bake;

parse

This method parses the given string if present, otherwise, the incoming Cookie header:

    my $cookies = $cookie->parse; #hash ref

    my %cookies = $cookie->parse;

    my %cookies = $cookie->parse($cookie_string);

fetch

Fetch and parse the incoming Cookie header:

    my $cookies = Apache::Cookie->fetch; #hash ref

    my %cookies = Apache::Cookie->fetch;

as_string

Format the cookie object as a string:

 #same as $cookie->bake
 $r->err_headers_out->add("Set-Cookie" => $cookie->as_string);

name

Get or set the name of the cookie:

 my $name = $cookie->name;

 $cookie->name("Foo");

value

Get or set the values of the cookie:

 my $value = $cookie->value;
 my @values = $cookie->value;

 $cookie->value("string");
 $cookie->value(\@array);

domain

Get or set the domain for the cookie:

 my $domain = $cookie->domain;
 $cookie->domain(".cp.net");

path

Get or set the path for the cookie:

 my $path = $cookie->path;
 $cookie->path("/");

expires

Get or set the expire time for the cookie:

 my $expires = $cookie->expires;
 $cookie->expires("+3h");

secure

Get or set the secure flag for the cookie:

 my $secure = $cookie->secure;
 $cookie->secure(1);

CAVEATS

The underlying C code for the Apache::Cookie module presents some unexpected results for Perl programmers when dealing with null bytes ('\0's) inside cookies. Native C commonly uses "null-terminated strings" when storing scalar string values. This means that C uses a '\0' byte to mark the end of the string(EOS). What this means for Perl programmers is that if you wish to create a cookie with a '\0' byte, the underlying C library will simply truncate the value at the '\0' byte. A cookie with the value '\0' will similarly simply be ignored, as the C library will not detect any content whatsoever. This problem is solved in the libapreq-2.0 library.

BUGS

RFC 2964-5 are not fully implemented.
value should also accept a hash ref as argument.
Reportedly does not run (linking problem?) on Apple's OSX

AUTHOR

Doug MacEachern, updated for v1.0 by Joe Schaefer updated for v1.1 by Issac Goldstand