[Summary view] [Print] [Text view]

   1  <?php
   2  namespace GuzzleHttp\Cookie;
   3  
   4  use Psr\Http\Message\RequestInterface;
   5  use Psr\Http\Message\ResponseInterface;
   6  
   7  /**
   8   * Stores HTTP cookies.
   9   *
  10   * It extracts cookies from HTTP requests, and returns them in HTTP responses.
  11   * CookieJarInterface instances automatically expire contained cookies when
  12   * necessary. Subclasses are also responsible for storing and retrieving
  13   * cookies from a file, database, etc.
  14   *
  15   * @link http://docs.python.org/2/library/cookielib.html Inspiration
  16   */
  17  interface CookieJarInterface extends \Countable, \IteratorAggregate
  18  {
  19      /**
  20       * Create a request with added cookie headers.
  21       *
  22       * If no matching cookies are found in the cookie jar, then no Cookie
  23       * header is added to the request and the same request is returned.
  24       *
  25       * @param RequestInterface $request Request object to modify.
  26       *
  27       * @return RequestInterface returns the modified request.
  28       */
  29      public function withCookieHeader(RequestInterface $request);
  30  
  31      /**
  32       * Extract cookies from an HTTP response and store them in the CookieJar.
  33       *
  34       * @param RequestInterface  $request  Request that was sent
  35       * @param ResponseInterface $response Response that was received
  36       */
  37      public function extractCookies(
  38          RequestInterface $request,
  39          ResponseInterface $response
  40      );
  41  
  42      /**
  43       * Sets a cookie in the cookie jar.
  44       *
  45       * @param SetCookie $cookie Cookie to set.
  46       *
  47       * @return bool Returns true on success or false on failure
  48       */
  49      public function setCookie(SetCookie $cookie);
  50  
  51      /**
  52       * Remove cookies currently held in the cookie jar.
  53       *
  54       * Invoking this method without arguments will empty the whole cookie jar.
  55       * If given a $domain argument only cookies belonging to that domain will
  56       * be removed. If given a $domain and $path argument, cookies belonging to
  57       * the specified path within that domain are removed. If given all three
  58       * arguments, then the cookie with the specified name, path and domain is
  59       * removed.
  60       *
  61       * @param string|null $domain Clears cookies matching a domain
  62       * @param string|null $path   Clears cookies matching a domain and path
  63       * @param string|null $name   Clears cookies matching a domain, path, and name
  64       *
  65       * @return CookieJarInterface
  66       */
  67      public function clear($domain = null, $path = null, $name = null);
  68  
  69      /**
  70       * Discard all sessions cookies.
  71       *
  72       * Removes cookies that don't have an expire field or a have a discard
  73       * field set to true. To be called when the user agent shuts down according
  74       * to RFC 2965.
  75       */
  76      public function clearSessionCookies();
  77  
  78      /**
  79       * Converts the cookie jar to an array.
  80       *
  81       * @return array
  82       */
  83      public function toArray();
  84  }