[Summary view]

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