HTTP::CookieJar(3pm)

1HTTP::CookieJar(3)    User Contributed Perl Documentation   HTTP::CookieJar(3)
2
3
4

NAME

6       HTTP::CookieJar - A minimalist HTTP user agent cookie jar
7

VERSION

9       version 0.012
10

SYNOPSIS

12         use HTTP::CookieJar;
13
14         my $jar = HTTP::CookieJar->new;
15
16         # add cookie received from a request
17         $jar->add( "http://www.example.com/", "CUSTOMER=WILE_E_COYOTE; Path=/; Domain=example.com" );
18
19         # extract cookie header for a given request
20         my $cookie = $jar->cookie_header( "http://www.example.com/" );
21

DESCRIPTION

23       This module implements a minimalist HTTP user agent cookie jar in
24       conformance with RFC 6265 <http://tools.ietf.org/html/rfc6265>.
25
26       Unlike the commonly used HTTP::Cookies module, this module does not
27       require use of HTTP::Request and HTTP::Response objects.  An LWP-
28       compatible adapter is available as HTTP::CookieJar::LWP.
29

CONSTRUCTORS

31   new
32           my $jar = HTTP::CookieJar->new;
33
34       Return a new, empty cookie jar
35

METHODS

37   add
38           $jar->add(
39               "http://www.example.com/", "lang=en-US; Path=/; Domain=example.com"
40           );
41
42       Given a request URL and a "Set-Cookie" header string, attempts to adds
43       the cookie to the jar.  If the cookie is expired, instead it deletes
44       any matching cookie from the jar.  A "Max-Age" attribute will be
45       converted to an absolute "Expires" attribute.
46
47       It will throw an exception if the request URL is missing or invalid.
48       Returns true if successful cookie processing or undef/empty-list on
49       failure.
50
51   clear
52           $jar->clear
53
54       Empties the cookie jar.
55
56   cookies_for
57           my @cookies = $jar->cookies_for("http://www.example.com/foo/bar");
58
59       Given a request URL, returns a list of hash references representing
60       cookies that should be sent.  The hash references are copies --
61       changing values will not change the cookies in the jar.
62
63       Cookies set "secure" will only be returned if the request scheme is
64       "https".  Expired cookies will not be returned.
65
66       Keys of a cookie hash reference might include:
67
68       •   name -- the name of the cookie
69
70       •   value -- the value of the cookie
71
72       •   domain -- the domain name to which the cookie applies
73
74       •   path -- the path to which the cookie applies
75
76       •   expires -- if present, when the cookie expires in epoch seconds
77
78       •   secure -- if present, the cookie was set "Secure"
79
80       •   httponly -- if present, the cookie was set "HttpOnly"
81
82       •   hostonly -- if present, the cookie may only be used with the domain
83           as a host
84
85       •   creation_time -- epoch seconds since the cookie was first stored
86
87       •   last_access_time -- epoch seconds since the cookie was last stored
88
89       Keep in mind that "httponly" means it should only be used in requests
90       and not made available via Javascript, etc.  This is pretty meaningless
91       for Perl user agents.
92
93       Generally, user agents should use the "cookie_header" method instead.
94
95       It will throw an exception if the request URL is missing or invalid.
96
97   cookie_header
98           my $header = $jar->cookie_header("http://www.example.com/foo/bar");
99
100       Given a request URL, returns a correctly-formatted string with all
101       relevant cookies for the request.  This string is ready to be used in a
102       "Cookie" header in an HTTP request.  E.g.:
103
104           SID=31d4d96e407aad42; lang=en-US
105
106       It follows the same exclusion rules as "cookies_for".
107
108       If the request is invalid or no cookies apply, it will return an empty
109       string.
110
111   dump_cookies
112           my @list = $jar->dump_cookies;
113           my @list = $jar->dump_cookies( { persistent => 1 } );
114
115       Returns a list of raw cookies in string form.  The strings resemble
116       what would be received from "Set-Cookie" headers, but with additional
117       internal fields.  The list is only intended for use with "load_cookies"
118       to allow cookie jar persistence.
119
120       If a hash reference with a true "persistent" key is given as an
121       argument, cookies without an "Expires" time (i.e. "session cookies")
122       will be omitted.
123
124       Here is a trivial example of saving a cookie jar file with Path::Tiny:
125
126           path("jar.txt")->spew( join "\n", $jar->dump_cookies );
127
128   load_cookies
129           $jar->load_cookies( @cookies );
130
131       Given a list of cookie strings from "dump_cookies", it adds them to the
132       cookie jar.  Cookies added in this way will supersede any existing
133       cookies with similar domain, path and name.
134
135       It returns the jar object for convenience when loading a new object:
136
137           my $jar = HTTP::CookieJar->new->load_cookies( @cookies );
138
139       Here is a trivial example of loading a cookie jar file with Path::Tiny:
140
141           my $jar = HTTP::CookieJar->new->load_cookies(
142               path("jar.txt")->lines
143           );
144

LIMITATIONS AND CAVEATS

146   RFC 6265 vs prior standards
147       This modules adheres as closely as possible to the user-agent rules of
148       RFC 6265.  Therefore, it does not handle nor generate "Set-Cookie2" and
149       "Cookie2" headers, implement ".local" suffixes, or do path/domain
150       matching in accord with prior RFC's.
151
152   Internationalized domain names
153       Internationalized domain names given in requests must be properly
154       encoded in ASCII form.
155
156   Public suffixes
157       If Mozilla::PublicSuffix is installed, cookie domains will be checked
158       against the public suffix list.  Public suffix cookies are only allowed
159       as host-only cookies.
160
161   Third-party cookies
162       According to RFC 6265, a cookie may be accepted only if has no "Domain"
163       attribute (in which case it is "host-only") or if the "Domain"
164       attribute is a suffix of the request URL.  This effectively prohibits
165       Site A from setting a cookie for unrelated Site B, which is one
166       potential third-party cookie vector.
167

SUPPORT

174   Bugs / Feature Requests
175       Please report any bugs or feature requests through the issue tracker at
176       <https://github.com/dagolden/HTTP-CookieJar/issues>.  You will be
177       notified automatically of any progress on your issue.
178
179   Source Code
180       This is open source software.  The code repository is available for
181       public review and contribution under the terms of the license.
182
183       <https://github.com/dagolden/HTTP-CookieJar>
184
185         git clone https://github.com/dagolden/HTTP-CookieJar.git
186

AUTHOR

188       David Golden <dagolden@cpan.org>
189

CONTRIBUTORS

191       •   Dan Book <grinnz@grinnz.com>
192
193       •   David Golden <xdg@xdg.me>
194
195       •   jvolkening <jdv@base2bio.com>
196

COPYRIGHT AND LICENSE

198       This software is Copyright (c) 2013 by David Golden.
199
200       This is free software, licensed under:
201
202         The Apache License, Version 2.0, January 2004
203
204
205
206perl v5.34.0                      2021-07-22                HTTP::CookieJar(3)