.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Apache2::Cookie 3pm"
.TH Apache2::Cookie 3pm "2023-02-07" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Apache2::Cookie, Apache2::Cookie::Jar \- HTTP Cookies Class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Apache2::Cookie;
\&
\&    $j = Apache2::Cookie::Jar\->new($r);
\&    $c_in = $j\->cookies("foo");         # get cookie from request headers
\&
\&    $c_out = Apache2::Cookie\->new($r,
\&                                  \-name  => "mycookie",
\&                                  \-value => $c_in\->name );
\&
\&    $c_out\->path("/bar");               # set path to "/bar"
\&    $c_out\->bake;                       # send cookie in response headers
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Apache2::Cookie module is based on the original 1.X versions, which mimic
the CGI::Cookie \s-1API.\s0  The current version of this module includes several packages
and methods which are patterned after Apache2::Request, yet remain largely
backwards-compatible with the original 1.X \s-1API\s0 (see the \*(L"\s-1PORTING\s0 from 1.X\*(R" section
below for known issues).
.PP
This manpage documents the Apache2::Cookie and Apache2::Cookie::Jar packages.
.SH "Apache2::Cookie::Jar"
.IX Header "Apache2::Cookie::Jar"
This class collects Apache2::Cookie objects into a lookup table.  It plays
the same role for accessing the incoming cookies as Apache2::Request does for
accessing the incoming params and file uploads.
.SS "new"
.IX Subsection "new"
.Vb 1
\&    Apache2::Cookie::Jar\->new($env)
.Ve
.PP
Class method that retrieves the parsed cookie jar from the current
environment.
.SS "cookies"
.IX Subsection "cookies"
.Vb 2
\&    $jar\->cookies()
\&    $jar\->cookies($key)
.Ve
.PP
Retrieve cookies named \f(CW$key\fR with from the jar object.  In scalar
context the first such cookie is returned, and in list context the
full list of such cookies are returned.
.PP
If the \f(CW$key\fR argument is omitted, \f(CW\*(C`scalar $jar\->cookies()\*(C'\fR will
return an APR::Request::Cookie::Table object containing all the cookies in
the jar.  Modifications to the this object will affect the jar's
internal \fIcookies\fR table in \f(CW\*(C`apreq_jar_t\*(C'\fR, so their impact will
be noticed by all libapreq2 applications during this request.
.PP
In list context \f(CW\*(C`$jar\->cookies()\*(C'\fR returns the list of names
for all the cookies in the jar.  The order corresponds to the
order in which the cookies appeared in the incoming \*(L"Cookie\*(R" header.
.PP
This method will throw an \f(CW\*(C`APR::Request::Error\*(C'\fR object into $@ if
the returned value(s) could be unreliable.  In particular, note that
\&\f(CW\*(C`scalar $jar\->cookies("foo")\*(C'\fR will not croak if it can locate
the a \*(L"foo\*(R" cookie within the jar's parsed cookie table, even if the
cookie parser has failed (the cookies are parsed in the same order
as they appeared in the \*(L"Cookie\*(R" header). In all other circumstances
\&\f(CW\*(C`cookies\*(C'\fR will croak if the parser failed to successfully parse the
\&\*(L"Cookie\*(R" header.
.PP
.Vb 2
\&    $c = Apache2::Cookie\->new($r, name => "foo", value => 3);
\&    $j\->cookies\->add($c);
\&
\&    $cookie = $j\->cookies("foo");  # first foo cookie
\&    @cookies = $j\->cookies("foo"); # all foo cookies
\&    @names = $j\->cookies();        # all cookie names
.Ve
.SS "status"
.IX Subsection "status"
.Vb 1
\&    $jar\->status()
.Ve
.PP
Get the \fI\s-1APR\s0\fR status code of the cookie parser:
\&\s-1APR_SUCCESS\s0 on success, error otherwise.
.SH "Apache2::Cookie"
.IX Header "Apache2::Cookie"
.SS "new"
.IX Subsection "new"
.Vb 1
\&    Apache2::Cookie\->new($env, %args)
.Ve
.PP
Just like CGI::Cookie::new, but requires an additional environment argument:
.PP
.Vb 8
\&    $cookie = Apache2::Cookie\->new($r,
\&                             \-name    =>  \*(Aqfoo\*(Aq,
\&                             \-value   =>  \*(Aqbar\*(Aq,
\&                             \-expires =>  \*(Aq+3M\*(Aq,
\&                             \-domain  =>  \*(Aq.capricorn.com\*(Aq,
\&                             \-path    =>  \*(Aq/cgi\-bin/database\*(Aq,
\&                             \-secure  =>  1
\&                            );
.Ve
.PP
The \f(CW\*(C`\-value\*(C'\fR argument may be either an arrayref, a hashref, or
a string.  \f(CW\*(C`Apache2::Cookie::freeze\*(C'\fR encodes this argument into the
cookie's raw value.
.SS "freeze"
.IX Subsection "freeze"
.Vb 1
\&    Apache2::Cookie\->freeze($value)
.Ve
.PP
Helper function (for \f(CW\*(C`new\*(C'\fR) that serializes a new cookie's value in a
manner compatible with CGI::Cookie (and Apache2::Cookie 1.X).  This class
method accepts an arrayref, hashref, or normal perl string in \f(CW$value\fR.
.PP
.Vb 1
\&    $value = Apache2::Cookie\->freeze(["2+2", "=4"]);
.Ve
.SS "thaw"
.IX Subsection "thaw"
.Vb 2
\&    Apache2::Cookie\->thaw($value)
\&    $cookie\->thaw()
.Ve
.PP
This is the helper method (for \f(CW\*(C`value\*(C'\fR) responsible for decoding the
raw value of a cookie.  An optional argument \f(CW$value\fR may be used in
place of the cookie's raw value.  This method can also decode cookie
values created using CGI::Cookie or Apache2::Cookie 1.X.
.PP
.Vb 2
\&    print $cookie\->thaw;                    # prints "bar"
\&    @values = Apache2::Cookie\->thaw($value); # ( "2+2", "=4" )
.Ve
.SS "as_string"
.IX Subsection "as_string"
.Vb 1
\&    $cookie\->as_string()
.Ve
.PP
Format the cookie object as a string.  The quote-operator for Apache2::Cookie
is overloaded to run this method whenever a cookie appears in quotes.
.PP
.Vb 1
\&    ok "$cookie" eq $cookie\->as_string;
.Ve
.SS "name"
.IX Subsection "name"
.Vb 1
\&    $cookie\->name()
.Ve
.PP
Get the name of the cookie.
.SS "value"
.IX Subsection "value"
.Vb 1
\&    $cookie\->value()
.Ve
.PP
Get the (unswizzled) value of the cookie:
.PP
.Vb 2
\&    my $value = $cookie\->value;
\&    my @values = $cookie\->value;
.Ve
.PP
Note: if the cookie's value was created using a  \f(CW\*(C`freeze\*(C'\fR method,
one way to reconstitute the object is by subclassing
Apache2::Cookie with a package that provides the associated \f(CW\*(C`thaw\*(C'\fR sub:
.PP
.Vb 5
\&    {
\&        package My::COOKIE;
\&        @ISA = \*(AqApache2::Cookie\*(Aq;
\&        sub thaw { my $val = shift\->raw_value; $val =~ tr/a\-z/A\-Z/; $val }
\&    }
\&
\&    bless $cookie, "My::COOKIE";
\&
\&    ok $cookie\->value eq "BAR";
.Ve
.SS "raw_value"
.IX Subsection "raw_value"
.Vb 1
\&    $cookie\->raw_value()
.Ve
.PP
Gets the raw (opaque) value string as it appears in the incoming
\&\*(L"Cookie\*(R" header.
.PP
.Vb 1
\&    ok $cookie\->raw_value eq "bar";
.Ve
.SS "bake"
.IX Subsection "bake"
.Vb 1
\&    $cookie\->bake($r)
.Ve
.PP
Adds a \fISet-Cookie\fR header to the outgoing headers table.
.SS "bake2"
.IX Subsection "bake2"
.Vb 1
\&    $cookie\->bake2($r)
.Ve
.PP
Adds a \fISet\-Cookie2\fR header to the outgoing headers table.
.SS "domain"
.IX Subsection "domain"
.Vb 2
\&    $cookie\->domain()
\&    $cookie\->domain($set)
.Ve
.PP
Get or set the domain for the cookie:
.PP
.Vb 2
\&    $domain = $cookie\->domain;
\&    $cookie\->domain(".cp.net");
.Ve
.SS "path"
.IX Subsection "path"
.Vb 2
\&    $cookie\->path()
\&    $cookie\->path($set)
.Ve
.PP
Get or set the path for the cookie:
.PP
.Vb 2
\&    $path = $cookie\->path;
\&    $cookie\->path("/");
.Ve
.SS "version"
.IX Subsection "version"
.Vb 2
\&    $cookie\->version()
\&    $cookie\->version($set)
.Ve
.PP
Get or set the cookie version for this cookie.
Netscape spec cookies have version = 0;
RFC-compliant cookies have version = 1.
.PP
.Vb 3
\&    ok $cookie\->version == 0;
\&    $cookie\->version(1);
\&    ok $cookie\->version == 1;
.Ve
.SS "expires"
.IX Subsection "expires"
.Vb 2
\&    $cookie\->expires()
\&    $cookie\->expires($set)
.Ve
.PP
Get or set the future expire time for the cookie.  When
assigning, the new value ($set) should match /^\e+?(\ed+)([YMDhms]?)$/
\&\f(CW$2\fR qualifies the number in \f(CW$1\fR as representing \*(L"Y\*(R"ears, \*(L"M\*(R"onths,
\&\*(L"D\*(R"ays, \*(L"h\*(R"ours, \*(L"m\*(R"inutes, or \*(L"s\*(R"econds (if the qualifier is
omitted, the number is interpreted as representing seconds).
As a special case, \f(CW$set\fR = \*(L"now\*(R" is equivalent to \f(CW$set\fR = \*(L"0\*(R".
.PP
.Vb 2
\&    my $expires = $cookie\->expires;
\&    $cookie\->expires("+3h"); # cookie is set to expire in 3 hours
.Ve
.SS "secure"
.IX Subsection "secure"
.Vb 2
\&    $cookie\->secure()
\&    $cookie\->secure($set)
.Ve
.PP
Get or set the secure flag for the cookie:
.PP
.Vb 3
\&    $cookie\->secure(1);
\&    $is_secure = $cookie\->secure;
\&    $cookie\->secure(0);
.Ve
.SS "httponly"
.IX Subsection "httponly"
.Vb 2
\&    $cookie\->httponly()
\&    $cookie\->httponly($set)
.Ve
.PP
Get or set the HttpOnly flag for the cookie:
.PP
.Vb 3
\&    $cookie\->httponly(1);
\&    $is_HttpOnly = $cookie\->httponly;
\&    $cookie\->httponly(0);
.Ve
.SS "httponly"
.IX Subsection "httponly"
.Vb 2
\&    $cookie\->httponly()
\&    $cookie\->httponly($set)
.Ve
.PP
Get or set the HttpOnly flag for the cookie:
.PP
.Vb 3
\&    $cookie\->httponly(1);
\&    $is_HttpOnly = $cookie\->httponly;
\&    $cookie\->httponly(0);
.Ve
.SS "comment"
.IX Subsection "comment"
.Vb 2
\&    $cookie\->comment()
\&    $cookie\->comment($set)
.Ve
.PP
Get or set the comment field of an \s-1RFC\s0 (Version > 0) cookie.
.PP
.Vb 2
\&    $cookie\->comment("Never eat yellow snow");
\&    print $cookie\->comment;
.Ve
.SS "commentURL"
.IX Subsection "commentURL"
.Vb 2
\&    $cookie\->commentURL()
\&    $cookie\->commentURL($set)
.Ve
.PP
Get or set the commentURL field of an \s-1RFC\s0 (Version > 0) cookie.
.PP
.Vb 2
\&    $cookie\->commentURL("http://localhost/cookie.policy");
\&    print $cookie\->commentURL;
.Ve
.SS "fetch"
.IX Subsection "fetch"
.Vb 1
\&    Apache2::Cookie\->fetch($r)
.Ve
.PP
Fetch and parse the incoming \fICookie\fR header:
.PP
.Vb 1
\&    my $cookies = Apache2::Cookie\->fetch($r); # APR::Request::Cookie::Table ref
\&
\&    It should be noted, that with perl 5.8+ Iterator magic, table is able
\&    to handle multiple cookies of the same name.
\&
\&    my %cookies = Apache2::Cookie\->fetch($r);
.Ve
.SH "PORTING from 1.X"
.IX Header "PORTING from 1.X"
Changes to the 1.X \s-1API:\s0
.IP "\(bu" 5
\&\f(CW\*(C`Apache2::Cookie::fetch\*(C'\fR now expects an \f(CW$r\fR object as (second)
        argument, although this isn't necessary in mod_perl 2 if
        \f(CW\*(C`Apache2::RequestUtil\*(C'\fR is loaded and 'PerlOptions +GlobalRequest'
        is in effect.
.IP "\(bu" 5
\&\f(CW\*(C`Apache2::Cookie::parse\*(C'\fR is gone.
.IP "\(bu" 5
\&\f(CW\*(C`Apache2::Cookie::new\*(C'\fR no longer encodes the supplied cookie name.
.IP "\(bu" 5
\&\f(CW\*(C`Apache2::Cookie::new()\*(C'\fR returns undef if \-value is not specified
        or \-value => undef.
.IP "\(bu" 5
\&\f(CW\*(C`name()\*(C'\fR and \f(CW\*(C`value()\*(C'\fR no longer accept a \*(L"set\*(R" argument. In other words,
        neither a cookie's name, nor its value, may be modified.  A new cookie
        should be made instead.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Apache2::Request, APR::Request::Cookie,
APR::Request::Error, \fBCGI::Cookie\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 6
\&  Licensed to the Apache Software Foundation (ASF) under one or more
\&  contributor license agreements.  See the NOTICE file distributed with
\&  this work for additional information regarding copyright ownership.
\&  The ASF licenses this file to You under the Apache License, Version 2.0
\&  (the "License"); you may not use this file except in compliance with
\&  the License.  You may obtain a copy of the License at
\&
\&      http://www.apache.org/licenses/LICENSE\-2.0
\&
\&  Unless required by applicable law or agreed to in writing, software
\&  distributed under the License is distributed on an "AS IS" BASIS,
\&  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
\&  See the License for the specific language governing permissions and
\&  limitations under the License.
.Ve