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.

Apache::Cookie 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 
                    );
            
          

The -value attribute may be either an arrayref, a hashref, or an object with a freeze method. The <freeze> method must serialize the object in a manner compatible with the "value" portion of the Cookie specs. Specifically, it must take care to avoid header tokens [;,=] and whitespace characters in its output.

bake

Add a Set-Cookie header to the outgoing headers table.

            

              
              
$cookie->bake;
            
          

bake2

Add a Set-Cookie2 header to the outgoing headers table.

            

              
              
$cookie->bake2;
            
          

fetch

Fetch and parse the incoming Cookie header:

            

              
              
my $cookies = Apache::Cookie->fetch($r); #hash ref
my %cookies = Apache::Cookie->fetch($r);
            
          

as_string

Format the cookie object as a string:

            

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

name

Get the name of the cookie:

            

              
              
my $name = $cookie->name;
            
          

value

Get the value of the cookie:

            

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

Note: if the cookie's value was serialized from an object possessing a freeze method, one way to reconstitute the object is by subclassing Apache::Cookie with a package that provides the associated thaw sub:

            

              
              
package My::Cookie;
use base 'Apache::Cookie';
sub thaw { ... }
bless $cookie, __PACKAGE__;
my $obj = $cookie->value;  # same as $cookie->thaw($cookie->raw_value);
            
          

raw_value

Gets the raw (opaque) value string as it appears in the incoming "Cookie" header.

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);
            
          

CHANGES to the v1 API:

• Apache::Cookie::fetch requires an $r object as (second) argument.

• Apache::Cookie::parse is gone.

• Apache::Cookie::new can take an object as its -value arg, assuming the object has a valid freeze method.

• name and <value> no longer accept a "set" argument. In other words, neither a cookie's name, nor its value, may be modified. A new cookie should be made instead.

BUGS

SEE ALSO

Apache(3), Apache::Request(3), CGI::Cookie(3)

AUTHORS

Doug MacEachern, Joe Schaefer, Issac Goldstand

MISSING DOCS

Apache::Cookie::Jar, Apache::Cookie::Table

cpanm MySubClass

perl -MCPAN -e shell
install MySubClass