1<?php
2
3namespace Psr\Cache;
4
5/**
6 * CacheItemInterface defines an interface for interacting with objects inside a cache.
7 *
8 * Each Item object MUST be associated with a specific key, which can be set
9 * according to the implementing system and is typically passed by the
10 * Cache\CacheItemPoolInterface object.
11 *
12 * The Cache\CacheItemInterface object encapsulates the storage and retrieval of
13 * cache items. Each Cache\CacheItemInterface is generated by a
14 * Cache\CacheItemPoolInterface object, which is responsible for any required
15 * setup as well as associating the object with a unique Key.
16 * Cache\CacheItemInterface objects MUST be able to store and retrieve any type
17 * of PHP value defined in the Data section of the specification.
18 *
19 * Calling Libraries MUST NOT instantiate Item objects themselves. They may only
20 * be requested from a Pool object via the getItem() method.  Calling Libraries
21 * SHOULD NOT assume that an Item created by one Implementing Library is
22 * compatible with a Pool from another Implementing Library.
23 */
24interface CacheItemInterface
25{
26    /**
27     * Returns the key for the current cache item.
28     *
29     * The key is loaded by the Implementing Library, but should be available to
30     * the higher level callers when needed.
31     *
32     * @return string
33     *   The key string for this cache item.
34     */
35    public function getKey();
36
37    /**
38     * Retrieves the value of the item from the cache associated with this object's key.
39     *
40     * The value returned must be identical to the value originally stored by set().
41     *
42     * If isHit() returns false, this method MUST return null. Note that null
43     * is a legitimate cached value, so the isHit() method SHOULD be used to
44     * differentiate between "null value was found" and "no value was found."
45     *
46     * @return mixed
47     *   The value corresponding to this cache item's key, or null if not found.
48     */
49    public function get();
50
51    /**
52     * Confirms if the cache item lookup resulted in a cache hit.
53     *
54     * Note: This method MUST NOT have a race condition between calling isHit()
55     * and calling get().
56     *
57     * @return bool
58     *   True if the request resulted in a cache hit. False otherwise.
59     */
60    public function isHit();
61
62    /**
63     * Sets the value represented by this cache item.
64     *
65     * The $value argument may be any item that can be serialized by PHP,
66     * although the method of serialization is left up to the Implementing
67     * Library.
68     *
69     * @param mixed $value
70     *   The serializable value to be stored.
71     *
72     * @return static
73     *   The invoked object.
74     */
75    public function set($value);
76
77    /**
78     * Sets the expiration time for this cache item.
79     *
80     * @param \DateTimeInterface|null $expiration
81     *   The point in time after which the item MUST be considered expired.
82     *   If null is passed explicitly, a default value MAY be used. If none is set,
83     *   the value should be stored permanently or for as long as the
84     *   implementation allows.
85     *
86     * @return static
87     *   The called object.
88     */
89    public function expiresAt($expiration);
90
91    /**
92     * Sets the expiration time for this cache item.
93     *
94     * @param int|\DateInterval|null $time
95     *   The period of time from the present after which the item MUST be considered
96     *   expired. An integer parameter is understood to be the time in seconds until
97     *   expiration. If null is passed explicitly, a default value MAY be used.
98     *   If none is set, the value should be stored permanently or for as long as the
99     *   implementation allows.
100     *
101     * @return static
102     *   The called object.
103     */
104    public function expiresAfter($time);
105}
106