NAME
   HTTP::CookieJar - A minimalist HTTP user agent cookie jar

VERSION
   version 0.006

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
   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 module, this module does not
   require use of HTTP::Request and HTTP::Response objects. An
   LWP-compatible adapter is available as HTTP::CookieJar::LWP.

CONSTRUCTORS
 new
       my $jar = HTTP::CookieJar->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 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
       );

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

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

 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 <[email protected]>

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

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.