1CGI::Simple::Cookie(3)User Contributed Perl DocumentationCGI::Simple::Cookie(3)
2
3
4

NAME

6       CGI::Simple::Cookie - Interface to HTTP cookies
7

SYNOPSIS

9           use CGI::Simple::Standard qw(header);
10           use CGI::Simple::Cookie;
11
12           # Create new cookies and send them
13           $cookie1 = CGI::Simple::Cookie->new( -name=>'ID', -value=>123456 );
14           $cookie2 = CGI::Simple::Cookie->new( -name=>'preferences',
15                                               -value=>{ font => Helvetica,
16                                                         size => 12 }
17                                             );
18           print header( -cookie=>[$cookie1,$cookie2] );
19
20           # fetch existing cookies
21           %cookies = CGI::Simple::Cookie->fetch;
22           $id = $cookies{'ID'}->value;
23
24           # create cookies returned from an external source
25           %cookies = CGI::Simple::Cookie->parse($ENV{COOKIE});
26

DESCRIPTION

28       CGI::Simple::Cookie is an interface to HTTP/1.1 cookies, a mechanism
29       that allows Web servers to store persistent information on the
30       browser's side of the connection. Although CGI::Simple::Cookie is
31       intended to be used in conjunction with CGI::Simple (and is in fact
32       used by it internally), you can use this module independently.
33
34       For full information on cookies see:
35
36           http://tools.ietf.org/html/rfc2109
37           http://tools.ietf.org/html/rfc2965
38

USING CGI::Simple::Cookie

40       CGI::Simple::Cookie is object oriented.  Each cookie object has a name
41       and a value.  The name is any scalar value.  The value is any scalar or
42       array value (associative arrays are also allowed).  Cookies also have
43       several optional attributes, including:
44
45       1. expiration date
46           The expiration date tells the browser how long to hang on to the
47           cookie.  If the cookie specifies an expiration date in the future,
48           the browser will store the cookie information in a disk file and
49           return it to the server every time the user reconnects (until the
50           expiration date is reached).  If the cookie species an expiration
51           date in the past, the browser will remove the cookie from the disk
52           file.  If the expiration date is not specified, the cookie will
53           persist only until the user quits the browser.
54
55       2. domain
56           This is a partial or complete domain name for which the cookie is
57           valid.  The browser will return the cookie to any host that matches
58           the partial domain name.  For example, if you specify a domain name
59           of ".capricorn.com", then the browser will return the cookie to web
60           servers running on any of the machines "www.capricorn.com",
61           "ftp.capricorn.com", "feckless.capricorn.com", etc.  Domain names
62           must contain at least two periods to prevent attempts to match on
63           top level domains like ".edu".  If no domain is specified, then the
64           browser will only return the cookie to servers on the host the
65           cookie originated from.
66
67       3. path
68           If you provide a cookie path attribute, the browser will check it
69           against your script's URL before returning the cookie.  For
70           example, if you specify the path "/cgi-bin", then the cookie will
71           be returned to each of the scripts "/cgi-bin/tally.pl",
72           "/cgi-bin/order.pl", and "/cgi-bin/customer_service/complain.pl",
73           but not to the script "/cgi-private/site_admin.pl".  By default,
74           the path is set to "/", so that all scripts at your site will
75           receive the cookie.
76
77       4. secure flag
78           If the "secure" attribute is set, the cookie will only be sent to
79           your script if the CGI request is occurring on a secure channel,
80           such as SSL.
81
82       5. HttpOnly flag
83           If the "httponly" attribute is set, the cookie will only be
84           accessible through HTTP Requests. This cookie will be inaccessible
85           via JavaScript (to prevent XSS attacks).
86
87           See this URL for more information including supported browsers:
88
89           <http://www.owasp.org/index.php/HTTPOnly>
90
91       6. samesite flag
92           Allowed settings are "Strict", "Lax" and "None".
93
94           As of April 2018, support is limited mostly to recent releases of
95           Chrome and Opera.
96
97           <https://tools.ietf.org/html/draft-west-first-party-cookies-07>
98
99   Creating New Cookies
100           $c = CGI::Simple::Cookie->new( -name    =>  'foo',
101                                         -value    =>  'bar',
102                                         -expires  =>  '+3M',
103                                         -max-age  =>  '+3M',
104                                         -domain   =>  '.capricorn.com',
105                                         -path     =>  '/cgi-bin/database',
106                                         -secure   =>  1,
107                                         -samesite =>  'Lax',
108                                       );
109
110       Create cookies from scratch with the new method.  The -name and -value
111       parameters are required.  The name must be a scalar value.  The value
112       can be a scalar, an array reference, or a hash reference.  (At some
113       point in the future cookies will support one of the Perl object
114       serialization protocols for full generality).
115
116       -expires accepts any of the relative or absolute date formats
117       recognized by CGI::Simple, for example "+3M" for three months in the
118       future.  See CGI::Simple's documentation for details.
119
120       -max-age accepts the same data formats as -expires, but sets a relative
121       value instead of an absolute like -expires. This is intended to be more
122       secure since a clock could be changed to fake an absolute time. In
123       practice, as of 2011, "-max-age" still does not enjoy the widespread
124       support that "-expires" has. You can set both, and browsers that
125       support "-max-age" should ignore the "Expires" header. The drawback to
126       this approach is the bit of bandwidth for sending an extra header on
127       each cookie.
128
129       -domain points to a domain name or to a fully qualified host name.  If
130       not specified, the cookie will be returned only to the Web server that
131       created it.
132
133       -path points to a partial URL on the current server.  The cookie will
134       be returned to all URLs beginning with the specified path.  If not
135       specified, it defaults to '/', which returns the cookie to all pages at
136       your site.
137
138       -secure if set to a true value instructs the browser to return the
139       cookie only when a cryptographic protocol is in use.
140
141       -httponly if set to a true value, the cookie will not be accessible via
142       JavaScript.
143
144       -samesite may be "Lax", "Strict" or "None" and is an evolving part of
145       the standards for cookies. Please refer to current documentation
146       regarding it.
147
148   Sending the Cookie to the Browser
149       Within a CGI script you can send a cookie to the browser by creating
150       one or more Set-Cookie: fields in the HTTP header.  Here is a typical
151       sequence:
152
153           $c = CGI::Simple::Cookie->new( -name    =>  'foo',
154                                          -value   =>  ['bar','baz'],
155                                          -expires =>  '+3M'
156                                         );
157
158           print "Set-Cookie: $c\n";
159           print "Content-Type: text/html\n\n";
160
161       To send more than one cookie, create several Set-Cookie: fields.
162       Alternatively, you may concatenate the cookies together with "; " and
163       send them in one field.
164
165       If you are using CGI::Simple, you send cookies by providing a -cookie
166       argument to the header() method:
167
168         print header( -cookie=>$c );
169
170       Mod_perl users can set cookies using the request object's header_out()
171       method:
172
173         $r->header_out('Set-Cookie',$c);
174
175       Internally, Cookie overloads the "" operator to call its as_string()
176       method when incorporated into the HTTP header.  as_string() turns the
177       Cookie's internal representation into an RFC-compliant text
178       representation.  You may call as_string() yourself if you prefer:
179
180           print "Set-Cookie: ",$c->as_string,"\n";
181
182   Recovering Previous Cookies
183           %cookies = CGI::Simple::Cookie->fetch;
184
185       fetch returns an associative array consisting of all cookies returned
186       by the browser.  The keys of the array are the cookie names.  You can
187       iterate through the cookies this way:
188
189           %cookies = CGI::Simple::Cookie->fetch;
190           foreach (keys %cookies) {
191               do_something($cookies{$_});
192           }
193
194       In a scalar context, fetch() returns a hash reference, which may be
195       more efficient if you are manipulating multiple cookies.
196
197       CGI::Simple uses the URL escaping methods to save and restore reserved
198       characters in its cookies.  If you are trying to retrieve a cookie set
199       by a foreign server, this escaping method may trip you up.  Use
200       raw_fetch() instead, which has the same semantics as fetch(), but
201       performs no unescaping.
202
203       You may also retrieve cookies that were stored in some external form
204       using the parse() class method:
205
206              $COOKIES = `cat /usr/tmp/Cookie_stash`;
207              %cookies = CGI::Simple::Cookie->parse($COOKIES);
208
209   Manipulating Cookies
210       Cookie objects have a series of accessor methods to get and set cookie
211       attributes.  Each accessor has a similar syntax.  Called without
212       arguments, the accessor returns the current value of the attribute.
213       Called with an argument, the accessor changes the attribute and returns
214       its new value.
215
216       name()
217           Get or set the cookie's name.  Example:
218
219               $name = $c->name;
220               $new_name = $c->name('fred');
221
222       value()
223           Get or set the cookie's value.  Example:
224
225               $value = $c->value;
226               @new_value = $c->value(['a','b','c','d']);
227
228           value() is context sensitive.  In a list context it will return the
229           current value of the cookie as an array.  In a scalar context it
230           will return the first value of a multivalued cookie.
231
232       domain()
233           Get or set the cookie's domain.
234
235       path()
236           Get or set the cookie's path.
237
238       expires()
239           Get or set the cookie's expiration time.
240
241       max_age()
242           Get or set the cookie's maximum age.
243
244       secure()
245           Get or set the cookie's secure flag.
246
247       httponly()
248           Get or set the cookie's HttpOnly flag.
249
250       samesite()
251           Get or set the cookie's samesite value.
252

AUTHOR INFORMATION

254       Original version copyright 1997-1998, Lincoln D. Stein.  All rights
255       reserved.  Originally copyright 2001 Dr James Freeman
256       <jfreeman@tassie.net.au> This release by Andy Armstrong
257       <andy@hexten.net>
258
259       This library is free software; you can redistribute it and/or modify it
260       under the same terms as Perl itself.
261
262       Address bug reports and comments to: andy@hexten.net
263

BUGS

265       This section intentionally left blank :-)
266

SEE ALSO

268       CGI::Carp, CGI::Simple
269
270
271
272perl v5.36.0                      2023-01-20            CGI::Simple::Cookie(3)
Impressum