Apache2::Cookie(3pm)

1Apache2::Cookie(3)    User Contributed Perl Documentation   Apache2::Cookie(3)
2
3
4

NAME

6       Apache2::Cookie, Apache2::Cookie::Jar - HTTP Cookies Class
7

SYNOPSIS

9           use Apache2::Cookie;
10
11           $j = Apache2::Cookie::Jar->new($r);
12           $c_in = $j->cookies("foo");         # get cookie from request headers
13
14           $c_out = Apache2::Cookie->new($r,
15                                         -name  => "mycookie",
16                                         -value => $c_in->name );
17
18           $c_out->path("/bar");               # set path to "/bar"
19           $c_out->bake($r);                   # send cookie in response headers
20

DESCRIPTION

22       The Apache2::Cookie module is based on the original 1.X versions, which
23       mimic the CGI::Cookie API.  The current version of this module includes
24       several packages and methods which are patterned after
25       Apache2::Request, yet remain largely backwards-compatible with the
26       original 1.X API (see the "PORTING from 1.X" section below for known
27       issues).
28
29       This manpage documents the Apache2::Cookie and Apache2::Cookie::Jar
30       packages.
31

33       This class collects Apache2::Cookie objects into a lookup table.  It
34       plays the same role for accessing the incoming cookies as
35       Apache2::Request does for accessing the incoming params and file
36       uploads.
37
38   new
39           Apache2::Cookie::Jar->new($env)
40
41       Class method that retrieves the parsed cookie jar from the current
42       environment.
43
44   cookies
45           $jar->cookies()
46           $jar->cookies($key)
47
48       Retrieve cookies named $key with from the jar object.  In scalar
49       context the first such cookie is returned, and in list context the full
50       list of such cookies are returned.
51
52       If the $key argument is omitted, "scalar $jar->cookies()" will return
53       an APR::Request::Cookie::Table object containing all the cookies in the
54       jar.  Modifications to the this object will affect the jar's internal
55       cookies table in "apreq_jar_t", so their impact will be noticed by all
56       libapreq2 applications during this request.
57
58       In list context "$jar->cookies()" returns the list of names for all the
59       cookies in the jar.  The order corresponds to the order in which the
60       cookies appeared in the incoming "Cookie" header.
61
62       This method will throw an "APR::Request::Error" object into $@ if the
63       returned value(s) could be unreliable.  In particular, note that
64       "scalar $jar->cookies("foo")" will not croak if it can locate the a
65       "foo" cookie within the jar's parsed cookie table, even if the cookie
66       parser has failed (the cookies are parsed in the same order as they
67       appeared in the "Cookie" header). In all other circumstances "cookies"
68       will croak if the parser failed to successfully parse the "Cookie"
69       header.
70
71           $c = Apache2::Cookie->new($r, name => "foo", value => 3);
72           $j->cookies->add($c);
73
74           $cookie = $j->cookies("foo");  # first foo cookie
75           @cookies = $j->cookies("foo"); # all foo cookies
76           @names = $j->cookies();        # all cookie names
77
78   status
79           $jar->status()
80
81       Get the APR status code of the cookie parser: APR_SUCCESS on success,
82       error otherwise.
83

85   new
86           Apache2::Cookie->new($env, %args)
87
88       Just like CGI::Cookie::new, but requires an additional environment
89       argument:
90
91           $cookie = Apache2::Cookie->new($r,
92                                    -name    =>  'foo',
93                                    -value   =>  'bar',
94                                    -expires =>  '+3M',
95                                    -domain  =>  '.capricorn.com',
96                                    -path    =>  '/cgi-bin/database',
97                                    -secure  =>  1
98                                   );
99
100       The "-value" argument may be either an arrayref, a hashref, or a
101       string.  "Apache2::Cookie::freeze" encodes this argument into the
102       cookie's raw value.
103
104   freeze
105           Apache2::Cookie->freeze($value)
106
107       Helper function (for "new") that serializes a new cookie's value in a
108       manner compatible with CGI::Cookie (and Apache2::Cookie 1.X).  This
109       class method accepts an arrayref, hashref, or normal perl string in
110       $value.
111
112           $value = Apache2::Cookie->freeze(["2+2", "=4"]);
113
114   thaw
115           Apache2::Cookie->thaw($value)
116           $cookie->thaw()
117
118       This is the helper method (for "value") responsible for decoding the
119       raw value of a cookie.  An optional argument $value may be used in
120       place of the cookie's raw value.  This method can also decode cookie
121       values created using CGI::Cookie or Apache2::Cookie 1.X.
122
123           print $cookie->thaw;                    # prints "bar"
124           @values = Apache2::Cookie->thaw($value); # ( "2+2", "=4" )
125
126   as_string
127           $cookie->as_string()
128
129       Format the cookie object as a string.  The quote-operator for
130       Apache2::Cookie is overloaded to run this method whenever a cookie
131       appears in quotes.
132
133           ok "$cookie" eq $cookie->as_string;
134
135   name
136           $cookie->name()
137
138       Get the name of the cookie.
139
140   value
141           $cookie->value()
142
143       Get the (unswizzled) value of the cookie:
144
145           my $value = $cookie->value;
146           my @values = $cookie->value;
147
148       Note: if the cookie's value was created using a  "freeze" method, one
149       way to reconstitute the object is by subclassing Apache2::Cookie with a
150       package that provides the associated "thaw" sub:
151
152           {
153               package My::COOKIE;
154               @ISA = 'Apache2::Cookie';
155               sub thaw { my $val = shift->raw_value; $val =~ tr/a-z/A-Z/; $val }
156           }
157
158           bless $cookie, "My::COOKIE";
159
160           ok $cookie->value eq "BAR";
161
162   raw_value
163           $cookie->raw_value()
164
165       Gets the raw (opaque) value string as it appears in the incoming
166       "Cookie" header.
167
168           ok $cookie->raw_value eq "bar";
169
170   bake
171           $cookie->bake($r)
172
173       Adds a Set-Cookie header to the outgoing headers table.
174
175   bake2
176           $cookie->bake2($r)
177
178       Adds a Set-Cookie2 header to the outgoing headers table.
179
180   domain
181           $cookie->domain()
182           $cookie->domain($set)
183
184       Get or set the domain for the cookie:
185
186           $domain = $cookie->domain;
187           $cookie->domain(".cp.net");
188
189   path
190           $cookie->path()
191           $cookie->path($set)
192
193       Get or set the path for the cookie:
194
195           $path = $cookie->path;
196           $cookie->path("/");
197
198   version
199           $cookie->version()
200           $cookie->version($set)
201
202       Get or set the cookie version for this cookie.  Netscape spec cookies
203       have version = 0; RFC-compliant cookies have version = 1.
204
205           ok $cookie->version == 0;
206           $cookie->version(1);
207           ok $cookie->version == 1;
208
209   expires
210           $cookie->expires()
211           $cookie->expires($set)
212
213       Get or set the future expire time for the cookie.  When assigning, the
214       new value ($set) should match /^\+?(\d+)([YMDhms]?)$/ $2 qualifies the
215       number in $1 as representing "Y"ears, "M"onths, "D"ays, "h"ours,
216       "m"inutes, or "s"econds (if the qualifier is omitted, the number is
217       interpreted as representing seconds).  As a special case, $set = "now"
218       is equivalent to $set = "0".
219
220           my $expires = $cookie->expires;
221           $cookie->expires("+3h"); # cookie is set to expire in 3 hours
222
223   secure
224           $cookie->secure()
225           $cookie->secure($set)
226
227       Get or set the secure flag for the cookie:
228
229           $cookie->secure(1);
230           $is_secure = $cookie->secure;
231           $cookie->secure(0);
232
233   httponly
234           $cookie->httponly()
235           $cookie->httponly($set)
236
237       Get or set the HttpOnly flag for the cookie:
238
239           $cookie->httponly(1);
240           $is_HttpOnly = $cookie->httponly;
241           $cookie->httponly(0);
242
243   comment
244           $cookie->comment()
245           $cookie->comment($set)
246
247       Get or set the comment field of an RFC (Version > 0) cookie.
248
249           $cookie->comment("Never eat yellow snow");
250           print $cookie->comment;
251
252   commentURL
253           $cookie->commentURL()
254           $cookie->commentURL($set)
255
256       Get or set the commentURL field of an RFC (Version > 0) cookie.
257
258           $cookie->commentURL("http://localhost/cookie.policy");
259           print $cookie->commentURL;
260
261   fetch
262           Apache2::Cookie->fetch($r)
263
264       Fetch and parse the incoming Cookie header:
265
266           my $cookies = Apache2::Cookie->fetch($r); # APR::Request::Cookie::Table ref
267
268           It should be noted, that with perl 5.8+ Iterator magic, table is able
269           to handle multiple cookies of the same name.
270
271           my %cookies = Apache2::Cookie->fetch($r);
272

PORTING from 1.X

274       Changes to the 1.X API:
275
276       •    "Apache2::Cookie::fetch" now expects an $r object as (second)
277                    argument, although this isn't necessary in mod_perl 2 if
278                    "Apache2::RequestUtil" is loaded and 'PerlOptions
279            +GlobalRequest'
280                    is in effect.
281
282       •    "Apache2::Cookie::parse" is gone.
283
284       •    "Apache2::Cookie::new" no longer encodes the supplied cookie name.
285
286       •    "Apache2::Cookie::new()" returns undef if -value is not specified
287                    or -value => undef.
288
289       •    "name()" and "value()" no longer accept a "set" argument. In other
290            words,
291                    neither a cookie's name, nor its value, may be modified.
292            A new cookie
293                    should be made instead.
294

COPYRIGHT

300         Licensed to the Apache Software Foundation (ASF) under one or more
301         contributor license agreements.  See the NOTICE file distributed with
302         this work for additional information regarding copyright ownership.
303         The ASF licenses this file to You under the Apache License, Version 2.0
304         (the "License"); you may not use this file except in compliance with
305         the License.  You may obtain a copy of the License at
306
307             http://www.apache.org/licenses/LICENSE-2.0
308
309         Unless required by applicable law or agreed to in writing, software
310         distributed under the License is distributed on an "AS IS" BASIS,
311         WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
312         See the License for the specific language governing permissions and
313         limitations under the License.
314
315
316
317perl v5.34.0                      2021-07-22                Apache2::Cookie(3)