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           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   httponly
244           $cookie->httponly()
245           $cookie->httponly($set)
246
247       Get or set the HttpOnly flag for the cookie:
248
249           $cookie->httponly(1);
250           $is_HttpOnly = $cookie->httponly;
251           $cookie->httponly(0);
252
253   comment
254           $cookie->comment()
255           $cookie->comment($set)
256
257       Get or set the comment field of an RFC (Version > 0) cookie.
258
259           $cookie->comment("Never eat yellow snow");
260           print $cookie->comment;
261
262   commentURL
263           $cookie->commentURL()
264           $cookie->commentURL($set)
265
266       Get or set the commentURL field of an RFC (Version > 0) cookie.
267
268           $cookie->commentURL("http://localhost/cookie.policy");
269           print $cookie->commentURL;
270
271   fetch
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)
287                    argument, although this isn't necessary in mod_perl 2 if
288                    "Apache2::RequestUtil" is loaded and 'PerlOptions
289            +GlobalRequest'
290                    is in effect.
291
292       ·    "Apache2::Cookie::parse" is gone.
293
294       ·    "Apache2::Cookie::new" no longer encodes the supplied cookie name.
295
296       ·    "Apache2::Cookie::new()" returns undef if -value is not specified
297                    or -value => undef.
298
299       ·    "name()" and "value()" no longer accept a "set" argument. In other
300            words,
301                    neither a cookie's name, nor its value, may be modified.
302            A new cookie
303                    should be made instead.
304

COPYRIGHT

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