NAME

CGI::Apache2::Wrapper::Cookie - cookies via libapreq2

SYNOPSIS

 use CGI::Apache2::Wrapper::Cookie;
 
 sub handler {
    my $r = shift;
    # create a new Cookie and add it to the headers
    my $cookie = CGI::Apache2::Wrapper::Cookie->new($r,
                                                    -name=>'ID',
                                                    -value=>123456);
    $cookie->bake();
    # fetch existing cookies
    my %cookies = CGI::Apache2::Wrapper::Cookie->fetch($r);
    my $id = $cookies{'ID'}->value;
    return Apache2::Const::OK;
 }

DESCRIPTION

This module provides a wrapper around Apache2::Cookie. Some methods are overridden in order to provide a CGI::Cookie-compatible interface.

Cookies are created with the new method:

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

with a mandatory first argument of the Apache2::RequestRec object $r. The remaining arguments are

-name
This is the name of the cookie (required)
-value
This is the value associated with the cookie (required)
-expires
This accepts any of the relative or absolute date formats recognized by CGI.pm, for example "+3M" for three months in the future. See CGI.pm for details.
-domain
This points to a domain name or to a fully qualified host name. If not specified, the cookie will be returned only to the Web server that created it.
-path
This points to a partial URL on the current server. The cookie will be returned to all URLs beginning with the specified path. If not specified, it defaults to '/', which returns the cookie to all pages at your site.
-secure
If set to a true value, this instructs the browser to return the cookie only when a cryptographic protocol is in use.

After creation, cookies can be sent to the browser in the appropriate header by $c->bake();.

Existing cookies can be fetched with %cookies = CGI::Apache2::Wrapper::Cookie->fetch($r);, which requires a mandatory argument of the Apache2::RequestRec object $r. In a scalar context, this returns a hash reference. The keys of the hash are the values of the name of the Cookie, while the values are the corresponding CGI::Apache2::Wrapper::Cookie object.

Methods

Available methods are

new
```
 my $c = CGI::Apache2::Wrapper::Cookie->new($r, %args);
```
This creates a new cookie. Mandatory arguments are the Apache2::RequestRec object $r, as well as the name and value specified in %args.
name
```
 my $name = $c->name();
```
This gets the cookie name.
value
```
 my $value = $c->value();
```
This gets the cookie value.

domain

 my $domain = $c->domain();
 my $new_domain = $c->domain('.pie-shop.com');

This gets or sets the domain of the cookie.

path

 my $path = $c->path();
 my $new_path = $c->path('/basket/');

This gets or sets the path of the cookie.

secure

 my $secure = $c->secure();
 my $new_secure_setting = $c->secure(1);

This gets or sets the security setting of the cookie.

expires
```
  $c->expires('+3M');
```
This sets the expires setting of the cookie. In the current behaviour of Apache2::Cookie, this requires a mandatory setting, and doesn't return anything.
bake
```
 $c->bake();
```
This will send the cookie to the browser by adding the stringified version of the cookie to the Set-Cookie field of the HTTP header.
fetch
```
 %cookies = CGI::Apache2::Wrapper::Cookie->fetch($r);
```
This fetches existing cookies, and requires a mandatory argument of the Apache2::RequestRec object $r. In a scalar context, this returns a hash reference. The keys of the hash are the values of the name of the Cookie, while the values are the corresponding CGI::Apache2::Wrapper::Cookie object.

SUPPORT

You can find documentation for this module with the perldoc command:

    perldoc CGI::Apache2::Wrapper::Cookie

You can also look for information at:

AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/CGI-Apache2-Wrapper
CPAN::Forum: Discussion forum
http:///www.cpanforum.com/dist/CGI-Apache2-Wrapper
CPAN Ratings
http://cpanratings.perl.org/d/CGI-Apache2-Wrapper
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=CGI-Apache2-Wrapper
Search CPAN
http://search.cpan.org/dist/CGI-Apache2-Wrapper
UWinnipeg CPAN Search
http://cpan.uwinnipeg.ca/dist/CGI-Apache2-Wrapper

ENVIRONMENT VARIABLES

If the USE_CGI_PM environment variable is set, the new method will return a CGI::Cookie object, while fetch will return the corresponding cookies using CGI::Cookie.