.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
.\"
.\" 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" ''
'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 turned on, 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.
.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
.el \{\
. de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Apache2::Cookie 3"
.TH Apache2::Cookie 3 "2009-03-06" "perl v5.16.3" "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 "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, \fICGI::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
y~or5J ={Eeu磝Qk ᯘG{?+]ן?wM3X^歌>{7پK>on\jy R g/=fOroNVv~Y+ NGuÝHWyw[eQʨSb> >}Gmx[o[<{Ϯ_qF vM IENDB`
