1<?php
2
3namespace GuzzleHttp\Cookie;
4
5use Psr\Http\Message\RequestInterface;
6use 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 * @see https://docs.python.org/2/library/cookielib.html Inspiration
17 *
18 * @extends \IteratorAggregate<SetCookie>
19 */
20interface CookieJarInterface extends \Countable, \IteratorAggregate
21{
22    /**
23     * Create a request with added cookie headers.
24     *
25     * If no matching cookies are found in the cookie jar, then no Cookie
26     * header is added to the request and the same request is returned.
27     *
28     * @param RequestInterface $request Request object to modify.
29     *
30     * @return RequestInterface returns the modified request.
31     */
32    public function withCookieHeader(RequestInterface $request): RequestInterface;
33
34    /**
35     * Extract cookies from an HTTP response and store them in the CookieJar.
36     *
37     * @param RequestInterface  $request  Request that was sent
38     * @param ResponseInterface $response Response that was received
39     */
40    public function extractCookies(RequestInterface $request, ResponseInterface $response): void;
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): bool;
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    public function clear(string $domain = null, string $path = null, string $name = null): void;
66
67    /**
68     * Discard all sessions cookies.
69     *
70     * Removes cookies that don't have an expire field or a have a discard
71     * field set to true. To be called when the user agent shuts down according
72     * to RFC 2965.
73     */
74    public function clearSessionCookies(): void;
75
76    /**
77     * Converts the cookie jar to an array.
78     */
79    public function toArray(): array;
80}
81