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

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

PORTING from 1.X

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

COPYRIGHT

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