Debian Codegraph @

docs/html/group__apreq__xs__cookie.html

raw
1 <html>
2 <head>
3 <link rel="stylesheet" type="text/css" href="dox.css" />
4 <title>libapreq2-2.17: Apache2::Cookie</title>
5 </head>
6 <body>
7 <div id="page-header">
8 <p class="menu">
9 <a href="http://www.apache.org/">Apache Software Foundation</a> &gt; <a href="http://httpd.apache.org">HTTP Server Project</a> &gt;
10 <a href="http://httpd.apache.org/apreq/">Request Library Subproject</a></p>
11 <p class="apache">Apache HTTP Server Request Library</p>
12 <img alt="" src="feather.gif" /></div>
13 <!-- Generated by Doxygen 1.9.1 -->
14 <script type="text/javascript" src="menudata.js"></script>
15 <script type="text/javascript" src="menu.js"></script>
16 <script type="text/javascript">
17 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
18 $(function() {
19 initMenu('',false,false,'search.php','Search');
20 });
21 /* @license-end */</script>
22 <div id="main-nav"></div>
23 </div><!-- top -->
24 <div class="header">
25 <div class="headertitle">
26 <div class="title">Apache2::Cookie<div class="ingroups"><a class="el" href="group__apreq__lang.html">Language Bindings</a> &raquo; <a class="el" href="group__apreq__xs.html">Perl</a></div></div> </div>
27 </div><!--header-->
28 <div class="contents">
29
30
31
32
33 <ul id="index">
34 <li><a href="#NAME">NAME</a></li>
35 <li><a href="#SYNOPSIS">SYNOPSIS</a></li>
36 <li><a href="#DESCRIPTION">DESCRIPTION</a></li>
37 <li><a href="#Apache2::Cookie::Jar">Apache2::Cookie::Jar</a>
38 <ul>
39 <li><a href="#new">new</a></li>
40 <li><a href="#cookies">cookies</a></li>
41 <li><a href="#status">status</a></li>
42 </ul>
43 </li>
44 <li><a href="#Apache2::Cookie">Apache2::Cookie</a>
45 <ul>
46 <li><a href="#new1">new</a></li>
47 <li><a href="#freeze">freeze</a></li>
48 <li><a href="#thaw">thaw</a></li>
49 <li><a href="#as_string">as_string</a></li>
50 <li><a href="#name">name</a></li>
51 <li><a href="#value">value</a></li>
52 <li><a href="#raw_value">raw_value</a></li>
53 <li><a href="#bake">bake</a></li>
54 <li><a href="#bake2">bake2</a></li>
55 <li><a href="#domain">domain</a></li>
56 <li><a href="#path">path</a></li>
57 <li><a href="#version">version</a></li>
58 <li><a href="#expires">expires</a></li>
59 <li><a href="#secure">secure</a></li>
60 <li><a href="#httponly">httponly</a></li>
61 <li><a href="#comment">comment</a></li>
62 <li><a href="#commentURL">commentURL</a></li>
63 <li><a href="#fetch">fetch</a></li>
64 </ul>
65 </li>
66 <li><a href="#PORTING-from-1.X">PORTING from 1.X</a></li>
67 <li><a href="#SEE-ALSO">SEE ALSO</a></li>
68 <li><a href="#COPYRIGHT">COPYRIGHT</a></li>
69 </ul>
70
71 <h1 id="NAME">NAME</h1>
72
73 <p>Apache2::Cookie, Apache2::Cookie::Jar - HTTP Cookies Class</p>
74
75 <h1 id="SYNOPSIS">SYNOPSIS</h1>
76
77 <pre><code>use Apache2::Cookie;
78
79 $j = Apache2::Cookie::Jar-&gt;new($r);
80 $c_in = $j-&gt;cookies(&quot;foo&quot;); # get cookie from request headers
81
82 $c_out = Apache2::Cookie-&gt;new($r,
83 -name =&gt; &quot;mycookie&quot;,
84 -value =&gt; $c_in-&gt;name );
85
86 $c_out-&gt;path(&quot;/bar&quot;); # set path to &quot;/bar&quot;
87 $c_out-&gt;bake($r); # send cookie in response headers</code></pre>
88
89 <h1 id="DESCRIPTION">DESCRIPTION</h1>
90
91 <p>The Apache2::Cookie module is based on the original 1.X versions, which mimic the CGI::Cookie API. 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 API (see the <a href="#PORTING-from-1.X">&quot;PORTING from 1.X&quot;</a> section below for known issues).</p>
92
93 <p>This manpage documents the Apache2::Cookie and Apache2::Cookie::Jar packages.</p>
94
95 <h1 id="Apache2::Cookie::Jar">Apache2::Cookie::Jar</h1>
96
97 <p>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.</p>
98
99 <h2 id="new">new</h2>
100
101 <pre><code>Apache2::Cookie::Jar-&gt;new($env)</code></pre>
102
103 <p>Class method that retrieves the parsed cookie jar from the current environment.</p>
104
105 <h2 id="cookies">cookies</h2>
106
107 <pre><code>$jar-&gt;cookies()
108 $jar-&gt;cookies($key)</code></pre>
109
110 <p>Retrieve cookies named $key 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.</p>
111
112 <p>If the $key argument is omitted, <code>scalar $jar-&gt;cookies()</code> will return an APR::Request::Cookie::Table object containing all the cookies in the jar. Modifications to the this object will affect the jar&#39;s internal <i>cookies</i> table in <code>apreq_jar_t</code>, so their impact will be noticed by all libapreq2 applications during this request.</p>
113
114 <p>In list context <code>$jar-&gt;cookies()</code> 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 &quot;Cookie&quot; header.</p>
115
116 <p>This method will throw an <code>APR::Request::Error</code> object into $@ if the returned value(s) could be unreliable. In particular, note that <code>scalar $jar-&gt;cookies(&quot;foo&quot;)</code> will not croak if it can locate the a &quot;foo&quot; cookie within the jar&#39;s parsed cookie table, even if the cookie parser has failed (the cookies are parsed in the same order as they appeared in the &quot;Cookie&quot; header). In all other circumstances <code>cookies</code> will croak if the parser failed to successfully parse the &quot;Cookie&quot; header.</p>
117
118 <pre><code>$c = Apache2::Cookie-&gt;new($r, name =&gt; &quot;foo&quot;, value =&gt; 3);
119 $j-&gt;cookies-&gt;add($c);
120
121 $cookie = $j-&gt;cookies(&quot;foo&quot;); # first foo cookie
122 @cookies = $j-&gt;cookies(&quot;foo&quot;); # all foo cookies
123 @names = $j-&gt;cookies(); # all cookie names</code></pre>
124
125 <h2 id="status">status</h2>
126
127 <pre><code>$jar-&gt;status()</code></pre>
128
129 <p>Get the <i>APR</i> status code of the cookie parser: APR_SUCCESS on success, error otherwise.</p>
130
131 <h1 id="Apache2::Cookie">Apache2::Cookie</h1>
132
133 <h2 id="new1">new</h2>
134
135 <pre><code>Apache2::Cookie-&gt;new($env, %args)</code></pre>
136
137 <p>Just like CGI::Cookie::new, but requires an additional environment argument:</p>
138
139 <pre><code>$cookie = Apache2::Cookie-&gt;new($r,
140 -name =&gt; &#39;foo&#39;,
141 -value =&gt; &#39;bar&#39;,
142 -expires =&gt; &#39;+3M&#39;,
143 -domain =&gt; &#39;.capricorn.com&#39;,
144 -path =&gt; &#39;/cgi-bin/database&#39;,
145 -secure =&gt; 1
146 );</code></pre>
147
148 <p>The <code>-value</code> argument may be either an arrayref, a hashref, or a string. <code>Apache2::Cookie::freeze</code> encodes this argument into the cookie&#39;s raw value.</p>
149
150 <h2 id="freeze">freeze</h2>
151
152 <pre><code>Apache2::Cookie-&gt;freeze($value)</code></pre>
153
154 <p>Helper function (for <code>new</code>) that serializes a new cookie&#39;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 $value.</p>
155
156 <pre><code>$value = Apache2::Cookie-&gt;freeze([&quot;2+2&quot;, &quot;=4&quot;]);</code></pre>
157
158 <h2 id="thaw">thaw</h2>
159
160 <pre><code>Apache2::Cookie-&gt;thaw($value)
161 $cookie-&gt;thaw()</code></pre>
162
163 <p>This is the helper method (for <code>value</code>) responsible for decoding the raw value of a cookie. An optional argument $value may be used in place of the cookie&#39;s raw value. This method can also decode cookie values created using CGI::Cookie or Apache2::Cookie 1.X.</p>
164
165 <pre><code>print $cookie-&gt;thaw; # prints &quot;bar&quot;
166 @values = Apache2::Cookie-&gt;thaw($value); # ( &quot;2+2&quot;, &quot;=4&quot; )</code></pre>
167
168 <h2 id="as_string">as_string</h2>
169
170 <pre><code>$cookie-&gt;as_string()</code></pre>
171
172 <p>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.</p>
173
174 <pre><code>ok &quot;$cookie&quot; eq $cookie-&gt;as_string;</code></pre>
175
176 <h2 id="name">name</h2>
177
178 <pre><code>$cookie-&gt;name()</code></pre>
179
180 <p>Get the name of the cookie.</p>
181
182 <h2 id="value">value</h2>
183
184 <pre><code>$cookie-&gt;value()</code></pre>
185
186 <p>Get the (unswizzled) value of the cookie:</p>
187
188 <pre><code>my $value = $cookie-&gt;value;
189 my @values = $cookie-&gt;value;</code></pre>
190
191 <p>Note: if the cookie&#39;s value was created using a <code>freeze</code> method, one way to reconstitute the object is by subclassing Apache2::Cookie with a package that provides the associated <code>thaw</code> sub:</p>
192
193 <pre><code>{
194 package My::COOKIE;
195 @ISA = &#39;Apache2::Cookie&#39;;
196 sub thaw { my $val = shift-&gt;raw_value; $val =~ tr/a-z/A-Z/; $val }
197 }
198
199 bless $cookie, &quot;My::COOKIE&quot;;
200
201 ok $cookie-&gt;value eq &quot;BAR&quot;;</code></pre>
202
203 <h2 id="raw_value">raw_value</h2>
204
205 <pre><code>$cookie-&gt;raw_value()</code></pre>
206
207 <p>Gets the raw (opaque) value string as it appears in the incoming &quot;Cookie&quot; header.</p>
208
209 <pre><code>ok $cookie-&gt;raw_value eq &quot;bar&quot;;</code></pre>
210
211 <h2 id="bake">bake</h2>
212
213 <pre><code>$cookie-&gt;bake($r)</code></pre>
214
215 <p>Adds a <i>Set-Cookie</i> header to the outgoing headers table.</p>
216
217 <h2 id="bake2">bake2</h2>
218
219 <pre><code>$cookie-&gt;bake2($r)</code></pre>
220
221 <p>Adds a <i>Set-Cookie2</i> header to the outgoing headers table.</p>
222
223 <h2 id="domain">domain</h2>
224
225 <pre><code>$cookie-&gt;domain()
226 $cookie-&gt;domain($set)</code></pre>
227
228 <p>Get or set the domain for the cookie:</p>
229
230 <pre><code>$domain = $cookie-&gt;domain;
231 $cookie-&gt;domain(&quot;.cp.net&quot;);</code></pre>
232
233 <h2 id="path">path</h2>
234
235 <pre><code>$cookie-&gt;path()
236 $cookie-&gt;path($set)</code></pre>
237
238 <p>Get or set the path for the cookie:</p>
239
240 <pre><code>$path = $cookie-&gt;path;
241 $cookie-&gt;path(&quot;/&quot;);</code></pre>
242
243 <h2 id="version">version</h2>
244
245 <pre><code>$cookie-&gt;version()
246 $cookie-&gt;version($set)</code></pre>
247
248 <p>Get or set the cookie version for this cookie. Netscape spec cookies have version = 0; RFC-compliant cookies have version = 1.</p>
249
250 <pre><code>ok $cookie-&gt;version == 0;
251 $cookie-&gt;version(1);
252 ok $cookie-&gt;version == 1;</code></pre>
253
254 <h2 id="expires">expires</h2>
255
256 <pre><code>$cookie-&gt;expires()
257 $cookie-&gt;expires($set)</code></pre>
258
259 <p>Get or set the future expire time for the cookie. When assigning, the new value ($set) should match /^\+?(\d+)([YMDhms]?)$/ $2 qualifies the number in $1 as representing &quot;Y&quot;ears, &quot;M&quot;onths, &quot;D&quot;ays, &quot;h&quot;ours, &quot;m&quot;inutes, or &quot;s&quot;econds (if the qualifier is omitted, the number is interpreted as representing seconds). As a special case, $set = &quot;now&quot; is equivalent to $set = &quot;0&quot;.</p>
260
261 <pre><code>my $expires = $cookie-&gt;expires;
262 $cookie-&gt;expires(&quot;+3h&quot;); # cookie is set to expire in 3 hours</code></pre>
263
264 <h2 id="secure">secure</h2>
265
266 <pre><code>$cookie-&gt;secure()
267 $cookie-&gt;secure($set)</code></pre>
268
269 <p>Get or set the secure flag for the cookie:</p>
270
271 <pre><code>$cookie-&gt;secure(1);
272 $is_secure = $cookie-&gt;secure;
273 $cookie-&gt;secure(0);</code></pre>
274
275 <h2 id="httponly">httponly</h2>
276
277 <pre><code>$cookie-&gt;httponly()
278 $cookie-&gt;httponly($set)</code></pre>
279
280 <p>Get or set the HttpOnly flag for the cookie:</p>
281
282 <pre><code>$cookie-&gt;httponly(1);
283 $is_HttpOnly = $cookie-&gt;httponly;
284 $cookie-&gt;httponly(0);</code></pre>
285
286 <h2 id="comment">comment</h2>
287
288 <pre><code>$cookie-&gt;comment()
289 $cookie-&gt;comment($set)</code></pre>
290
291 <p>Get or set the comment field of an RFC (Version &gt; 0) cookie.</p>
292
293 <pre><code>$cookie-&gt;comment(&quot;Never eat yellow snow&quot;);
294 print $cookie-&gt;comment;</code></pre>
295
296 <h2 id="commentURL">commentURL</h2>
297
298 <pre><code>$cookie-&gt;commentURL()
299 $cookie-&gt;commentURL($set)</code></pre>
300
301 <p>Get or set the commentURL field of an RFC (Version &gt; 0) cookie.</p>
302
303 <pre><code>$cookie-&gt;commentURL(&quot;http://localhost/cookie.policy&quot;);
304 print $cookie-&gt;commentURL;</code></pre>
305
306 <h2 id="fetch">fetch</h2>
307
308 <pre><code>Apache2::Cookie-&gt;fetch($r)</code></pre>
309
310 <p>Fetch and parse the incoming <i>Cookie</i> header:</p>
311
312 <pre><code>my $cookies = Apache2::Cookie-&gt;fetch($r); # APR::Request::Cookie::Table ref
313
314 It should be noted, that with perl 5.8+ Iterator magic, table is able
315 to handle multiple cookies of the same name.
316
317 my %cookies = Apache2::Cookie-&gt;fetch($r);</code></pre>
318
319 <h1 id="PORTING-from-1.X">PORTING from 1.X</h1>
320
321 <p>Changes to the 1.X API:</p>
322
323 <ul>
324
325 <li><p><code>Apache2::Cookie::fetch</code> now expects an <code>$r</code> object as (second) argument, although this isn&#39;t necessary in mod_perl 2 if <code>Apache2::RequestUtil</code> is loaded and &#39;PerlOptions +GlobalRequest&#39; is in effect.</p>
326
327 </li>
328 <li><p><code>Apache2::Cookie::parse</code> is gone.</p>
329
330 </li>
331 <li><p><code>Apache2::Cookie::new</code> no longer encodes the supplied cookie name.</p>
332
333 </li>
334 <li><p><code>Apache2::Cookie::new()</code> returns undef if -value is not specified or -value =&gt; undef.</p>
335
336 </li>
337 <li><p><code>name()</code> and <code>value()</code> no longer accept a &quot;set&quot; argument. In other words, neither a cookie&#39;s name, nor its value, may be modified. A new cookie should be made instead.</p>
338
339 </li>
340 </ul>
341
342 <h1 id="SEE-ALSO">SEE ALSO</h1>
343
344 <p><a>Apache2::Request</a>, <a>APR::Request::Cookie</a>, <a>APR::Request::Error</a>, CGI::Cookie(3)</p>
345
346 <h1 id="COPYRIGHT">COPYRIGHT</h1>
347
348 <pre><code>Licensed to the Apache Software Foundation (ASF) under one or more
349 contributor license agreements. See the NOTICE file distributed with
350 this work for additional information regarding copyright ownership.
351 The ASF licenses this file to You under the Apache License, Version 2.0
352 (the &quot;License&quot;); you may not use this file except in compliance with
353 the License. You may obtain a copy of the License at
354
355 http://www.apache.org/licenses/LICENSE-2.0
356
357 Unless required by applicable law or agreed to in writing, software
358 distributed under the License is distributed on an &quot;AS IS&quot; BASIS,
359 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
360 See the License for the specific language governing permissions and
361 limitations under the License.</code></pre>
362
363
364 </div><!-- contents -->
365 <div id="footer">
366 <p class="apache">
367 Copyright &copy; 2003-2006 <a href="http://www.apache.org">The Apache Software Foundation</a>.<br/>
368 See <a href="apreq_license.html">LICENSE</a>.</p>
369 <p class="menu">
370 <span style="color:#aaa">page generated by <a href="http://www.doxygen.org/"><code>doxygen</code></a>
371 version 1.9.1 on Thu Aug 18 2022</span>
372 </p>
373 </div>
374 </body>
375 </html>