1<?php
2namespace GuzzleHttp\Cookie;
3
4use Psr\Http\Message\RequestInterface;
5use 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 */
17interface 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}
85