new

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

Return a new, empty cookie jar

add

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

Given a request URL and a "Set-Cookie" header string, attempts to adds the cookie to the jar. If the cookie is expired, instead it deletes any matching cookie from the jar. A "Max-Age" attribute will be converted to an absolute "Expires" attribute.

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.

clear

    $jar->clear

Empties the cookie jar.

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.

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 seconds since the cookie was first stored
• last_access_time -- epoch seconds since the cookie was last stored

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.

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.

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.

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.

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
    );

RFC 6265 vs prior standards

Internationalized domain names

Public suffixes

Third-party cookies

Bugs / Feature Requests

Source Code

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

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