1<?php
2
3/*
4 * This file is part of the Stash package.
5 *
6 * (c) Robert Hafner <tedivm@tedivm.com>
7 *
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
10 */
11
12namespace Stash\Interfaces;
13
14use \Psr\Cache\CacheItemInterface;
15
16interface ItemInterface extends CacheItemInterface
17{
18    /**
19     * Sets the Parent Pool for the Item class to use.
20     *
21     * Typically called by Pool directly, and *must* be called before running caching functions.
22     *
23     * @param PoolInterface $driver
24     */
25    public function setPool(PoolInterface $driver);
26
27    /**
28     * Takes and sets the key and namespace.
29     *
30     * Typically called by Pool directly, and *must* be called before running caching functions.
31     *
32     * @param array       $key
33     * @param string|null $namespace
34     */
35    public function setKey(array $key, $namespace = null);
36
37    /**
38     * This disables any IO operations by this object, effectively preventing
39     * the reading and writing of new data.
40     *
41     * @return bool
42     */
43    public function disable();
44
45    /**
46     * Returns the key as a string. This is particularly useful when the Item is
47     * returned as a group of Items in an Iterator.
48     *
49     * @return string
50     */
51    public function getKey();
52
53    /**
54     * Clears the current Item. If hierarchical or "stackable" caching is being
55     * used this function will also remove children Items.
56     *
57     * @return bool
58     */
59    public function clear();
60
61    /**
62     * Returns the data retrieved from the cache. Since this can return false or
63     * null as a correctly cached value, the return value should not be used to
64     * determine successful retrieval of data- for that use the "isMiss()"
65     * function after call this one. If no value is stored at all then this
66     * function will return null.
67     *
68     * @return mixed
69     */
70    public function get();
71
72    /**
73     * Returns true if the cached item is valid and usable.
74     *
75     * @return bool
76     */
77    public function isHit();
78
79    /**
80     * Returns true if the cached item needs to be refreshed.
81     *
82     * @return bool
83     */
84    public function isMiss();
85
86    /**
87     * Enables stampede protection by marking this specific instance of the Item
88     * as the one regenerating the cache.
89     *
90     * @param  null $ttl
91     * @return bool
92     */
93    public function lock($ttl = null);
94
95    /**
96     * Takes and stores data for later retrieval. This data can be any php data,
97     * including arrays and object, except resources and objects which are
98     * unable to be serialized.
99     *
100     * @param  mixed $value bool
101     * @return self
102     */
103    public function set($value);
104
105    /**
106     * Extends the expiration on the current cached item. For some engines this
107     * can be faster than storing the item again.
108     *
109     * @param  null $ttl
110     * @return bool
111     */
112    public function extend($ttl = null);
113
114    /**
115     * Return true if caching is disabled
116     *
117     * @return bool True if caching is disabled.
118     */
119    public function isDisabled();
120
121    /**
122     * Sets a PSR\Logger style logging client to enable the tracking of errors.
123     *
124     * @param  \PSR\Log\LoggerInterface $logger
125     * @return bool
126     */
127    public function setLogger($logger);
128
129    /**
130     * Returns the record's creation time or false if it isn't set
131     *
132     * @return \DateTime
133     */
134    public function getCreation();
135
136    /**
137     * Returns the record's expiration timestamp or false if no expiration timestamp is set
138     *
139     * @return \DateTime
140     */
141    public function getExpiration();
142
143    /**
144    * Sets the expiration based off of an integer or DateInterval
145    *
146    * @param int|\DateInterval $time
147    * @return self
148    */
149    public function expiresAfter($time);
150
151    /**
152    * Sets the expiration to a specific time.
153    *
154    * @param \DateTimeInterface $expiration
155    * @return self
156    */
157    public function expiresAt($expiration);
158
159    /**
160    * Sets the expiration based off a an integer, date interval, or date
161    *
162    * @param mixed $ttl An integer, date interval, or date
163    * @return self
164    */
165    public function setTTL($ttl = null);
166
167    /**
168    * Set the cache invalidation method for this item.
169    *
170    * @see Stash\Invalidation
171    *
172    * @param int   $invalidation A Stash\Invalidation constant
173    * @param mixed $arg          First argument for invalidation method
174    * @param mixed $arg2         Second argument for invalidation method
175    */
176    public function setInvalidationMethod($invalidation, $arg = null, $arg2 = null);
177
178    /**
179    * Persists the Item's value to the backend storage.
180    *
181    * @return bool
182    */
183    public function save();
184}
185