1<?php
2/**
3 * Zend Framework (http://framework.zend.com/)
4 *
5 * @link      http://github.com/zendframework/zf2 for the canonical source repository
6 * @copyright Copyright (c) 2005-2015 Zend Technologies USA Inc. (http://www.zend.com)
7 * @license   http://framework.zend.com/license/new-bsd New BSD License
8 */
9
10namespace Zend\Cache\Storage;
11
12use Traversable;
13
14interface StorageInterface
15{
16    /**
17     * Set options.
18     *
19     * @param array|Traversable|Adapter\AdapterOptions $options
20     * @return StorageInterface Fluent interface
21     */
22    public function setOptions($options);
23
24    /**
25     * Get options
26     *
27     * @return Adapter\AdapterOptions
28     */
29    public function getOptions();
30
31    /* reading */
32
33    /**
34     * Get an item.
35     *
36     * @param  string  $key
37     * @param  bool $success
38     * @param  mixed   $casToken
39     * @return mixed Data on success, null on failure
40     * @throws \Zend\Cache\Exception\ExceptionInterface
41     */
42    public function getItem($key, & $success = null, & $casToken = null);
43
44    /**
45     * Get multiple items.
46     *
47     * @param  array $keys
48     * @return array Associative array of keys and values
49     * @throws \Zend\Cache\Exception\ExceptionInterface
50     */
51    public function getItems(array $keys);
52
53    /**
54     * Test if an item exists.
55     *
56     * @param  string $key
57     * @return bool
58     * @throws \Zend\Cache\Exception\ExceptionInterface
59     */
60    public function hasItem($key);
61
62    /**
63     * Test multiple items.
64     *
65     * @param  array $keys
66     * @return array Array of found keys
67     * @throws \Zend\Cache\Exception\ExceptionInterface
68     */
69    public function hasItems(array $keys);
70
71    /**
72     * Get metadata of an item.
73     *
74     * @param  string $key
75     * @return array|bool Metadata on success, false on failure
76     * @throws \Zend\Cache\Exception\ExceptionInterface
77     */
78    public function getMetadata($key);
79
80    /**
81     * Get multiple metadata
82     *
83     * @param  array $keys
84     * @return array Associative array of keys and metadata
85     * @throws \Zend\Cache\Exception\ExceptionInterface
86     */
87    public function getMetadatas(array $keys);
88
89    /* writing */
90
91    /**
92     * Store an item.
93     *
94     * @param  string $key
95     * @param  mixed  $value
96     * @return bool
97     * @throws \Zend\Cache\Exception\ExceptionInterface
98     */
99    public function setItem($key, $value);
100
101    /**
102     * Store multiple items.
103     *
104     * @param  array $keyValuePairs
105     * @return array Array of not stored keys
106     * @throws \Zend\Cache\Exception\ExceptionInterface
107     */
108    public function setItems(array $keyValuePairs);
109
110    /**
111     * Add an item.
112     *
113     * @param  string $key
114     * @param  mixed  $value
115     * @return bool
116     * @throws \Zend\Cache\Exception\ExceptionInterface
117     */
118    public function addItem($key, $value);
119
120    /**
121     * Add multiple items.
122     *
123     * @param  array $keyValuePairs
124     * @return array Array of not stored keys
125     * @throws \Zend\Cache\Exception\ExceptionInterface
126     */
127    public function addItems(array $keyValuePairs);
128
129    /**
130     * Replace an existing item.
131     *
132     * @param  string $key
133     * @param  mixed  $value
134     * @return bool
135     * @throws \Zend\Cache\Exception\ExceptionInterface
136     */
137    public function replaceItem($key, $value);
138
139    /**
140     * Replace multiple existing items.
141     *
142     * @param  array $keyValuePairs
143     * @return array Array of not stored keys
144     * @throws \Zend\Cache\Exception\ExceptionInterface
145     */
146    public function replaceItems(array $keyValuePairs);
147
148    /**
149     * Set an item only if token matches
150     *
151     * It uses the token received from getItem() to check if the item has
152     * changed before overwriting it.
153     *
154     * @param  mixed  $token
155     * @param  string $key
156     * @param  mixed  $value
157     * @return bool
158     * @throws \Zend\Cache\Exception\ExceptionInterface
159     * @see    getItem()
160     * @see    setItem()
161     */
162    public function checkAndSetItem($token, $key, $value);
163
164    /**
165     * Reset lifetime of an item
166     *
167     * @param  string $key
168     * @return bool
169     * @throws \Zend\Cache\Exception\ExceptionInterface
170     */
171    public function touchItem($key);
172
173    /**
174     * Reset lifetime of multiple items.
175     *
176     * @param  array $keys
177     * @return array Array of not updated keys
178     * @throws \Zend\Cache\Exception\ExceptionInterface
179     */
180    public function touchItems(array $keys);
181
182    /**
183     * Remove an item.
184     *
185     * @param  string $key
186     * @return bool
187     * @throws \Zend\Cache\Exception\ExceptionInterface
188     */
189    public function removeItem($key);
190
191    /**
192     * Remove multiple items.
193     *
194     * @param  array $keys
195     * @return array Array of not removed keys
196     * @throws \Zend\Cache\Exception\ExceptionInterface
197     */
198    public function removeItems(array $keys);
199
200    /**
201     * Increment an item.
202     *
203     * @param  string $key
204     * @param  int    $value
205     * @return int|bool The new value on success, false on failure
206     * @throws \Zend\Cache\Exception\ExceptionInterface
207     */
208    public function incrementItem($key, $value);
209
210    /**
211     * Increment multiple items.
212     *
213     * @param  array $keyValuePairs
214     * @return array Associative array of keys and new values
215     * @throws \Zend\Cache\Exception\ExceptionInterface
216     */
217    public function incrementItems(array $keyValuePairs);
218
219    /**
220     * Decrement an item.
221     *
222     * @param  string $key
223     * @param  int    $value
224     * @return int|bool The new value on success, false on failure
225     * @throws \Zend\Cache\Exception\ExceptionInterface
226     */
227    public function decrementItem($key, $value);
228
229    /**
230     * Decrement multiple items.
231     *
232     * @param  array $keyValuePairs
233     * @return array Associative array of keys and new values
234     * @throws \Zend\Cache\Exception\ExceptionInterface
235     */
236    public function decrementItems(array $keyValuePairs);
237
238    /* status */
239
240    /**
241     * Capabilities of this storage
242     *
243     * @return Capabilities
244     */
245    public function getCapabilities();
246}
247