README.md
1# NAME
2
3HTTP::Cookies - HTTP cookie jars
4
5# VERSION
6
7version 6.10
8
9# SYNOPSIS
10
11 use HTTP::Cookies;
12 $cookie_jar = HTTP::Cookies->new(
13 file => "$ENV{'HOME'}/lwp_cookies.dat",
14 autosave => 1,
15 );
16
17 use LWP;
18 my $browser = LWP::UserAgent->new;
19 $browser->cookie_jar($cookie_jar);
20
21Or for an empty and temporary cookie jar:
22
23 use LWP;
24 my $browser = LWP::UserAgent->new;
25 $browser->cookie_jar( {} );
26
27# DESCRIPTION
28
29This class is for objects that represent a "cookie jar" -- that is, a
30database of all the HTTP cookies that a given LWP::UserAgent object
31knows about.
32
33Cookies are a general mechanism which server side connections can use
34to both store and retrieve information on the client side of the
35connection. For more information about cookies refer to
36[Cookie Spec](http://curl.haxx.se/rfc/cookie_spec.html) and
37[Cookie Central](http://www.cookiecentral.com). This module also implements the
38new style cookies described in [RFC 2965](https://tools.ietf.org/html/rfc2965).
39The two variants of cookies are supposed to be able to coexist happily.
40
41Instances of the class _HTTP::Cookies_ are able to store a collection
42of Set-Cookie2: and Set-Cookie: headers and are able to use this
43information to initialize Cookie-headers in _HTTP::Request_ objects.
44The state of a _HTTP::Cookies_ object can be saved in and restored from
45files.
46
47# LIMITATIONS
48
49This module does not support [Public Suffix](https://publicsuffix.org/) encouraged by a more recent standard, [RFC
506265](https://tools.ietf.org/html/rfc6265).
51
52This module's shortcomings mean that a malicious Web site can set
53cookies to track your user agent across all sites under a top level
54domain. See `t/publicsuffix.t` in this module's distribution for
55details.
56
57[HTTP::CookieJar::LWP](https://metacpan.org/pod/HTTP%3A%3ACookieJar%3A%3ALWP) supports Public Suffix, but only provides a
58limited subset of this module's functionality and [does not
59support](https://metacpan.org/pod/HTTP%3A%3ACookieJar#LIMITATIONS-AND-CAVEATS) standards older than
60_RFC 6265_.
61
62# METHODS
63
64The following methods are provided:
65
66- $cookie\_jar = HTTP::Cookies->new
67
68 The constructor takes hash style parameters. The following
69 parameters are recognized:
70
71 file: name of the file to restore cookies from and save cookies to
72 autosave: save during destruction (bool)
73 ignore_discard: save even cookies that are requested to be discarded (bool)
74 hide_cookie2: do not add Cookie2 header to requests
75
76 Future parameters might include (not yet implemented):
77
78 max_cookies 300
79 max_cookies_per_domain 20
80 max_cookie_size 4096
81
82 no_cookies list of domain names that we never return cookies to
83
84- $cookie\_jar->get\_cookies( $url\_or\_domain )
85- $cookie\_jar->get\_cookies( $url\_or\_domain, $cookie\_key,... )
86
87 Returns a hash of the cookies that applies to the given URL. If a
88 domainname is given as argument, then a prefix of "https://" is assumed.
89
90 If one or more $cookie\_key parameters are provided return the given values,
91 or `undef` if the cookie isn't available.
92
93- $cookie\_jar->add\_cookie\_header( $request )
94
95 The add\_cookie\_header() method will set the appropriate Cookie:-header
96 for the _HTTP::Request_ object given as argument. The $request must
97 have a valid url attribute before this method is called.
98
99- $cookie\_jar->extract\_cookies( $response )
100
101 The extract\_cookies() method will look for Set-Cookie: and
102 Set-Cookie2: headers in the _HTTP::Response_ object passed as
103 argument. Any of these headers that are found are used to update
104 the state of the $cookie\_jar.
105
106- $cookie\_jar->set\_cookie( $version, $key, $val, $path, $domain, $port, $path\_spec, $secure, $maxage, $discard, \\%rest )
107
108 The set\_cookie() method updates the state of the $cookie\_jar. The
109 $key, $val, $domain, $port and $path arguments are strings. The
110 $path\_spec, $secure, $discard arguments are boolean values. The $maxage
111 value is a number indicating number of seconds that this cookie will
112 live. A value of $maxage <= 0 will delete this cookie. The $version argument
113 sets the version of the cookie; the default value is 0 ( original Netscape
114 spec ). Setting $version to another value indicates the RFC to which the
115 cookie conforms (e.g. version 1 for RFC 2109). %rest defines various other
116 attributes like "Comment" and "CommentURL".
117
118- $cookie\_jar->save
119- $cookie\_jar->save( $file )
120- $cookie\_jar->save( file => $file, ignore\_discard => $ignore\_discard )
121
122 This method file saves the state of the $cookie\_jar to a file.
123 The state can then be restored later using the load() method. If a
124 filename is not specified we will use the name specified during
125 construction. If the $ignore\_discard value is true (or not specified,
126 but attribute _ignore\_discard_ was set at cookie jar construction),
127 then we will even save cookies that are marked to be discarded.
128
129 The default is to save a sequence of "Set-Cookie3" lines.
130 "Set-Cookie3" is a proprietary LWP format, not known to be compatible
131 with any browser. The _HTTP::Cookies::Netscape_ sub-class can
132 be used to save in a format compatible with Netscape.
133
134- $cookie\_jar->load
135- $cookie\_jar->load( $file )
136
137 This method reads the cookies from the file and adds them to the
138 $cookie\_jar. The file must be in the format written by the save()
139 method.
140
141- $cookie\_jar->revert
142
143 This method empties the $cookie\_jar and re-loads the $cookie\_jar
144 from the last save file.
145
146- $cookie\_jar->clear
147- $cookie\_jar->clear( $domain )
148- $cookie\_jar->clear( $domain, $path )
149- $cookie\_jar->clear( $domain, $path, $key )
150
151 Invoking this method without arguments will empty the whole
152 $cookie\_jar. If given a single argument only cookies belonging to
153 that domain will be removed. If given two arguments, cookies
154 belonging to the specified path within that domain are removed. If
155 given three arguments, then the cookie with the specified key, path
156 and domain is removed.
157
158- $cookie\_jar->clear\_temporary\_cookies
159
160 Discard all temporary cookies. Scans for all cookies in the jar
161 with either no expire field or a true `discard` flag. To be
162 called when the user agent shuts down according to RFC 2965.
163
164- $cookie\_jar->scan( \\&callback )
165
166 The argument is a subroutine that will be invoked for each cookie
167 stored in the $cookie\_jar. The subroutine will be invoked with
168 the following arguments:
169
170 0 version
171 1 key
172 2 val
173 3 path
174 4 domain
175 5 port
176 6 path_spec
177 7 secure
178 8 expires
179 9 discard
180 10 hash
181
182- $cookie\_jar->as\_string
183- $cookie\_jar->as\_string( $skip\_discardables )
184
185 The as\_string() method will return the state of the $cookie\_jar
186 represented as a sequence of "Set-Cookie3" header lines separated by
187 "\\n". If $skip\_discardables is TRUE, it will not return lines for
188 cookies with the _Discard_ attribute.
189
190# SEE ALSO
191
192[HTTP::Cookies::Netscape](https://metacpan.org/pod/HTTP%3A%3ACookies%3A%3ANetscape), [HTTP::Cookies::Microsoft](https://metacpan.org/pod/HTTP%3A%3ACookies%3A%3AMicrosoft)
193
194# AUTHOR
195
196Gisle Aas <gisle@activestate.com>
197
198# COPYRIGHT AND LICENSE
199
200This software is copyright (c) 2002 by Gisle Aas.
201
202This is free software; you can redistribute it and/or modify it under
203the same terms as the Perl 5 programming language system itself.
204