# HTTP::CookieJar - A minimalist HTTP user agent cookie jar - perldoc - [phpMan]

## NAME
    [HTTP::CookieJar](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookieJar/markdown) - A minimalist HTTP user agent cookie jar

## VERSION
    version 0.014

## SYNOPSIS
      use [HTTP::CookieJar](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookieJar/markdown);

      my $jar = [HTTP::CookieJar](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookieJar/markdown)->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
    This module implements a minimalist HTTP user agent cookie jar in conformance with RFC 6265
    <<http://tools.ietf.org/html/rfc6265>>.

    Unlike the commonly used [HTTP::Cookies](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookies/markdown) module, this module does not require use of [HTTP::Request](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ARequest/markdown)
    and [HTTP::Response](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3AResponse/markdown) objects. An LWP-compatible adapter is available as [HTTP::CookieJar::LWP](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookieJar%3A%3ALWP/markdown).

## CONSTRUCTORS
  new
        my $jar = [HTTP::CookieJar](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookieJar/markdown)->new;

    Return a new, empty cookie jar

## 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, 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 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.

    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](https://www.chedong.com/phpMan.php/perldoc/Path%3A%3ATiny/markdown):

        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](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookieJar/markdown)->new->load_cookies( @cookies );

    Here is a trivial example of loading a cookie jar file with [Path::Tiny](https://www.chedong.com/phpMan.php/perldoc/Path%3A%3ATiny/markdown):

        my $jar = [HTTP::CookieJar](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookieJar/markdown)->new->load_cookies(
            path("jar.txt")->lines
        );

## LIMITATIONS AND CAVEATS
  RFC 6265 vs prior standards
    This modules 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.

### Internationalized domain names
    Internationalized domain names given in requests must be properly encoded in ASCII form.

### Public suffixes
    If [Mozilla::PublicSuffix](https://www.chedong.com/phpMan.php/perldoc/Mozilla%3A%3APublicSuffix/markdown) is installed, cookie domains will be checked against the public suffix
    list. Public suffix cookies are only allowed as host-only cookies.

### Third-party cookies
    According to RFC 6265, a cookie may be accepted only if 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.

## SEE ALSO
    *   [HTTP::Cookies](https://www.chedong.com/phpMan.php/perldoc/HTTP%3A%3ACookies/markdown)

    *   [Mojo::UserAgent::CookieJar](https://www.chedong.com/phpMan.php/perldoc/Mojo%3A%3AUserAgent%3A%3ACookieJar/markdown)

## 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.

### 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>>

## 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