HTTP::CookieJar(3)

🍪 HTTP::CookieJar 🍪

okay so bestie, this is the manual page for HTTP::CookieJar(3) from the User Contributed Perl Documentation, and it's literally a minimalist HTTP user agent cookie jar. no cap: tiny module, big cookie energy. 🍪✨

💖 NAME 💖

HTTP::CookieJar — a minimalist HTTP user agent cookie jar. that's the whole name, and honestly? iconic. 👑

✨ VERSION ✨

version 0.014 💅

🛠️ SYNOPSIS 🛠️

use HTTP::CookieJar;

my $jar = HTTP::CookieJar->new;

# add cookie received from a request
$jar->add( "http://www.example.com/", "CUSTOMER=WILE_E_COYOTE; Path=/; Domain=example.com" );

# extract cookie header for a given request
my $cookie = $jar->cookie_header( "http://www.example.com/" );

🌸 DESCRIPTION 🌸

so this module implements a minimalist HTTP user agent cookie jar in conformance with RFC 6265 (http://tools.ietf.org/html/rfc6265). it's giving “small but knows exactly what it's doing.” 🎀

unlike the commonly used HTTP::Cookies module, this module does not require use of HTTP::Request and HTTP::Response objects. an LWP-compatible adapter is available as HTTP::CookieJar::LWP. slay. 💅

🧚 CONSTRUCTORS 🧚

🎀 new 🎀

my $jar = HTTP::CookieJar->new;

returns a new, empty cookie jar. fresh jar, no crumbs, ready for business. 🫶

🔥 METHODS 🔥

🍓 add 🍓

$jar->add(
    "http://www.example.com/", "lang=en-US; Path=/; Domain=example.com"
);

given a request URL and a Set-Cookie header string, it attempts to add the cookie to the jar. if the cookie is expired, it instead deletes any matching cookie from the jar. a Max-Age attribute will be converted to an absolute Expires attribute. the way that expiration math gets handled? lowkey important. ⏳

it will throw an exception if the request URL is missing or invalid. returns true if successful cookie processing or undef/empty-list on failure. periodt.

🧼 clear 🧼

$jar->clear

empties the cookie jar. it's the “new phone who dis” of cookie storage. 💀

🦋 cookies_for 🦋

my @cookies = $jar->cookies_for("http://www.example.com/foo/bar");

given a request URL, returns a list of hash references representing cookies that should be sent. the hash references are copies — changing values will not change the cookies in the jar. no accidental side-eye mutations, bestie. 🙈

cookies set secure will only be returned if the request scheme is https. expired cookies will not be returned.

keys of a cookie hash reference might include:

• name — the name of the cookie
• value — the value of the cookie
• domain — the domain name to which the cookie applies
• path — the path to which the cookie applies
• expires — if present, when the cookie expires in epoch seconds
• secure — if present, the cookie was set Secure
• httponly — if present, the cookie was set HttpOnly
• hostonly — if present, the cookie may only be used with the domain as a host
• creation_time — epoch time when the cookie was first stored
• last_access_time — epoch time when the cookie was last accessed (i.e. "now")

keep in mind that httponly means it should only be used in requests and not made available via Javascript, etc. this is pretty meaningless for Perl user agents. ngl, Perl user agents are built different. 😭

generally, user agents should use the cookie_header method instead.

it will throw an exception if the request URL is missing or invalid.

🎀 cookie_header 🎀

my $header = $jar->cookie_header("http://www.example.com/foo/bar");

given a request URL, returns a correctly-formatted string with all relevant cookies for the request. this string is ready to be used in a Cookie header in an HTTP request. e.g.:

SID=31d4d96e407aad42; lang=en-US

it follows the same exclusion rules as cookies_for.

if the request is invalid or no cookies apply, it will return an empty string. respectful. clean. no notes. ✨

🍓 dump_cookies 🍓

my @list = $jar->dump_cookies;
my @list = $jar->dump_cookies( { persistent => 1 } );

returns a list of raw cookies in string form. the strings resemble what would be received from Set-Cookie headers, but with additional internal fields. the list is only intended for use with load_cookies to allow cookie jar persistence. it's giving “save your faves for later.” 💾💖

if a hash reference with a true persistent key is given as an argument, cookies without an Expires time (i.e. "session cookies") will be omitted.

here is a trivial example of saving a cookie jar file with Path::Tiny:

path("jar.txt")->spew( join "\n", $jar->dump_cookies );

🦋 load_cookies 🦋

$jar->load_cookies( @cookies );

given a list of cookie strings from dump_cookies, it adds them to the cookie jar. cookies added in this way will supersede any existing cookies with similar domain, path and name. new cookie era, same iconic jar. 👑

it returns the jar object for convenience when loading a new object:

my $jar = HTTP::CookieJar->new->load_cookies( @cookies );

here is a trivial example of loading a cookie jar file with Path::Tiny:

my $jar = HTTP::CookieJar->new->load_cookies(
    path("jar.txt")->lines
);

💀 LIMITATIONS AND CAVEATS 💀

bestie, this part is the “read the fine print” corner. it's not mean, it's just honest. 🫶

🌈 RFC 6265 vs prior standards 🌈

this module adheres as closely as possible to the user-agent rules of RFC 6265. therefore, it does not handle nor generate Set-Cookie2 and Cookie2 headers, implement .local suffixes, or do path/domain matching in accord with prior RFC's. it's very much “new RFC, new me,” and that's on purpose. 💅

🦋 Internationalized domain names 🦋

internationalized domain names given in requests must be properly encoded in ASCII form. no vibes-based encoding, okay? actual ASCII. 🔤

🌸 Public suffixes 🌸

if Mozilla::PublicSuffix is installed, cookie domains will be checked against the public suffix list. public suffix cookies are only allowed as host-only cookies. it's giving “boundaries, but make them standards-compliant.” 🚧

💀 Third-party cookies 💀

according to RFC 6265, a cookie may be accepted only if it has no Domain attribute (in which case it is "host-only") or if the Domain attribute is a suffix of the request URL. this effectively prohibits Site A from setting a cookie for unrelated Site B, which is one potential third-party cookie vector. not today, cross-site chaos. 🙅‍♀️

👀 SEE ALSO 👀

• HTTP::Cookies
• Mojo::UserAgent::CookieJar

🫶 SUPPORT 🫶

🐛 Bugs / Feature Requests 🐛

please report any bugs or feature requests through the issue tracker at https://github.com/dagolden/HTTP-CookieJar/issues. you will be notified automatically of any progress on your issue. communication? we love to see it. 💌

👑 Source Code 👑

this is open source software. the code repository is available for public review and contribution under the terms of the license.

https://github.com/dagolden/HTTP-CookieJar

git clone https://github.com/dagolden/HTTP-CookieJar.git

💜 AUTHOR 💜

David Golden <dagolden@cpan.org> — author icon. 🫡

🌟 CONTRIBUTORS 🌟

• Dan Book <grinnz@grinnz.com>
• David Golden <xdg@xdg.me>
• jvolkening <jdv@base2bio.com>

📜 COPYRIGHT AND LICENSE 📜

this software is Copyright (c) 2013 by David Golden.

this is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

xoxo, bestie 💋 — this page is HTTP::CookieJar(3), generated with perl v5.42.0 on 2025-07-16. mwah! 🎀