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.014
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 time when the cookie was first stored
86
87       •   last_access_time -- epoch time when the cookie was last accessed
88           (i.e. "now")
89
90       Keep in mind that "httponly" means it should only be used in requests
91       and not made available via Javascript, etc.  This is pretty meaningless
92       for Perl user agents.
93
94       Generally, user agents should use the "cookie_header" method instead.
95
96       It will throw an exception if the request URL is missing or invalid.
97
98   cookie_header
99           my $header = $jar->cookie_header("http://www.example.com/foo/bar");
100
101       Given a request URL, returns a correctly-formatted string with all
102       relevant cookies for the request.  This string is ready to be used in a
103       "Cookie" header in an HTTP request.  E.g.:
104
105           SID=31d4d96e407aad42; lang=en-US
106
107       It follows the same exclusion rules as "cookies_for".
108
109       If the request is invalid or no cookies apply, it will return an empty
110       string.
111
112   dump_cookies
113           my @list = $jar->dump_cookies;
114           my @list = $jar->dump_cookies( { persistent => 1 } );
115
116       Returns a list of raw cookies in string form.  The strings resemble
117       what would be received from "Set-Cookie" headers, but with additional
118       internal fields.  The list is only intended for use with "load_cookies"
119       to allow cookie jar persistence.
120
121       If a hash reference with a true "persistent" key is given as an
122       argument, cookies without an "Expires" time (i.e. "session cookies")
123       will be omitted.
124
125       Here is a trivial example of saving a cookie jar file with Path::Tiny:
126
127           path("jar.txt")->spew( join "\n", $jar->dump_cookies );
128
129   load_cookies
130           $jar->load_cookies( @cookies );
131
132       Given a list of cookie strings from "dump_cookies", it adds them to the
133       cookie jar.  Cookies added in this way will supersede any existing
134       cookies with similar domain, path and name.
135
136       It returns the jar object for convenience when loading a new object:
137
138           my $jar = HTTP::CookieJar->new->load_cookies( @cookies );
139
140       Here is a trivial example of loading a cookie jar file with Path::Tiny:
141
142           my $jar = HTTP::CookieJar->new->load_cookies(
143               path("jar.txt")->lines
144           );
145

LIMITATIONS AND CAVEATS

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

SUPPORT

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

AUTHOR

189       David Golden <dagolden@cpan.org>
190

CONTRIBUTORS

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

COPYRIGHT AND LICENSE

199       This software is Copyright (c) 2013 by David Golden.
200
201       This is free software, licensed under:
202
203         The Apache License, Version 2.0, January 2004
204
205
206
207perl v5.36.0                      2023-01-20                HTTP::CookieJar(3)