1<?php
2
3namespace Psr\Cache;
4
5/**
6 * CacheItemPoolInterface generates CacheItemInterface objects.
7 *
8 * The primary purpose of Cache\CacheItemPoolInterface is to accept a key from
9 * the Calling Library and return the associated Cache\CacheItemInterface object.
10 * It is also the primary point of interaction with the entire cache collection.
11 * All configuration and initialization of the Pool is left up to an
12 * Implementing Library.
13 */
14interface CacheItemPoolInterface
15{
16    /**
17     * Returns a Cache Item representing the specified key.
18     *
19     * This method must always return a CacheItemInterface object, even in case of
20     * a cache miss. It MUST NOT return null.
21     *
22     * @param string $key
23     *   The key for which to return the corresponding Cache Item.
24     *
25     * @throws InvalidArgumentException
26     *   If the $key string is not a legal value a \Psr\Cache\InvalidArgumentException
27     *   MUST be thrown.
28     *
29     * @return CacheItemInterface
30     *   The corresponding Cache Item.
31     */
32    public function getItem($key);
33
34    /**
35     * Returns a traversable set of cache items.
36     *
37     * @param string[] $keys
38     *   An indexed array of keys of items to retrieve.
39     *
40     * @throws InvalidArgumentException
41     *   If any of the keys in $keys are not a legal value a \Psr\Cache\InvalidArgumentException
42     *   MUST be thrown.
43     *
44     * @return array|\Traversable
45     *   A traversable collection of Cache Items keyed by the cache keys of
46     *   each item. A Cache item will be returned for each key, even if that
47     *   key is not found. However, if no keys are specified then an empty
48     *   traversable MUST be returned instead.
49     */
50    public function getItems(array $keys = array());
51
52    /**
53     * Confirms if the cache contains specified cache item.
54     *
55     * Note: This method MAY avoid retrieving the cached value for performance reasons.
56     * This could result in a race condition with CacheItemInterface::get(). To avoid
57     * such situation use CacheItemInterface::isHit() instead.
58     *
59     * @param string $key
60     *   The key for which to check existence.
61     *
62     * @throws InvalidArgumentException
63     *   If the $key string is not a legal value a \Psr\Cache\InvalidArgumentException
64     *   MUST be thrown.
65     *
66     * @return bool
67     *   True if item exists in the cache, false otherwise.
68     */
69    public function hasItem($key);
70
71    /**
72     * Deletes all items in the pool.
73     *
74     * @return bool
75     *   True if the pool was successfully cleared. False if there was an error.
76     */
77    public function clear();
78
79    /**
80     * Removes the item from the pool.
81     *
82     * @param string $key
83     *   The key to delete.
84     *
85     * @throws InvalidArgumentException
86     *   If the $key string is not a legal value a \Psr\Cache\InvalidArgumentException
87     *   MUST be thrown.
88     *
89     * @return bool
90     *   True if the item was successfully removed. False if there was an error.
91     */
92    public function deleteItem($key);
93
94    /**
95     * Removes multiple items from the pool.
96     *
97     * @param string[] $keys
98     *   An array of keys that should be removed from the pool.
99
100     * @throws InvalidArgumentException
101     *   If any of the keys in $keys are not a legal value a \Psr\Cache\InvalidArgumentException
102     *   MUST be thrown.
103     *
104     * @return bool
105     *   True if the items were successfully removed. False if there was an error.
106     */
107    public function deleteItems(array $keys);
108
109    /**
110     * Persists a cache item immediately.
111     *
112     * @param CacheItemInterface $item
113     *   The cache item to save.
114     *
115     * @return bool
116     *   True if the item was successfully persisted. False if there was an error.
117     */
118    public function save(CacheItemInterface $item);
119
120    /**
121     * Sets a cache item to be persisted later.
122     *
123     * @param CacheItemInterface $item
124     *   The cache item to save.
125     *
126     * @return bool
127     *   False if the item could not be queued or if a commit was attempted and failed. True otherwise.
128     */
129    public function saveDeferred(CacheItemInterface $item);
130
131    /**
132     * Persists any deferred cache items.
133     *
134     * @return bool
135     *   True if all not-yet-saved items were successfully saved or there were none. False otherwise.
136     */
137    public function commit();
138}
139