1HTTP::CookieJar(3) User Contributed Perl Documentation HTTP::CookieJar(3)
2
6 HTTP::CookieJar - A minimalist HTTP user agent cookie jar
7
9 version 0.010
10
12 use HTTP::CookieJar;
13 my $jar = HTTP::CookieJar->new;
15 # add cookie received from a request
17 $jar->add( "http://www.example.com/", "CUSTOMER=WILE_E_COYOTE; Path=/; Domain=example.com" );
18 # extract cookie header for a given request
20 my $cookie = $jar->cookie_header( "http://www.example.com/" );
21
23 This module implements a minimalist HTTP user agent cookie jar in
24 conformance with RFC 6265 <http://tools.ietf.org/html/rfc6265>.
25 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
31 new
32 my $jar = HTTP::CookieJar->new;
33 Return a new, empty cookie jar
35
37 add
38 $jar->add(
39 "http://www.example.com/", "lang=en-US; Path=/; Domain=example.com"
40 );
41 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 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 clear
52 $jar->clear
53 Empties the cookie jar.
55 cookies_for
57 my @cookies = $jar->cookies_for("http://www.example.com/foo/bar");
58 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 Cookies set "secure" will only be returned if the request scheme is
64 "https". Expired cookies will not be returned.
65 Keys of a cookie hash reference might include:
67 • name -- the name of the cookie
69 • value -- the value of the cookie
71 • domain -- the domain name to which the cookie applies
73 • path -- the path to which the cookie applies
75 • expires -- if present, when the cookie expires in epoch seconds
77 • secure -- if present, the cookie was set "Secure"
79 • httponly -- if present, the cookie was set "HttpOnly"
81 • hostonly -- if present, the cookie may only be used with the domain
83 as a host
84 • creation_time -- epoch seconds since the cookie was first stored
86 • last_access_time -- epoch seconds since the cookie was last stored
88 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 Generally, user agents should use the "cookie_header" method instead.
94 It will throw an exception if the request URL is missing or invalid.
96 cookie_header
98 my $header = $jar->cookie_header("http://www.example.com/foo/bar");
99 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 SID=31d4d96e407aad42; lang=en-US
105 It follows the same exclusion rules as "cookies_for".
107 If the request is invalid or no cookies apply, it will return an empty
109 string.
110 dump_cookies
112 my @list = $jar->dump_cookies;
113 my @list = $jar->dump_cookies( { persistent => 1 } );
114 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 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 Here is a trivial example of saving a cookie jar file with Path::Tiny:
125 path("jar.txt")->spew( join "\n", $jar->dump_cookies );
127 load_cookies
129 $jar->load_cookies( @cookies );
130 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 It returns the jar object for convenience when loading a new object:
136 my $jar = HTTP::CookieJar->new->load_cookies( @cookies );
138 Here is a trivial example of loading a cookie jar file with Path::Tiny:
140 my $jar = HTTP::CookieJar->new->load_cookies(
142 path("jar.txt")->lines
143 );
144
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 Internationalized domain names
153 Internationalized domain names given in requests must be properly
154 encoded in ASCII form.
155 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 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
169 • HTTP::Cookies
170 • Mojo::UserAgent::CookieJar
172
174 David Golden <dagolden@cpan.org>
175
177 • Dan Book <grinnz@grinnz.com>
178 • David Golden <xdg@xdg.me>
180 • jvolkening <jdv@base2bio.com>
182
184 This software is Copyright (c) 2013 by David Golden.
185 This is free software, licensed under:
187 The Apache License, Version 2.0, January 2004
189perl v5.32.1 2021-01-27 HTTP::CookieJar(3)