PSR-6 缓存接口规范

 1namespace Psr\Cache;
 2
 3/**
 4 * CacheItemInterface 定了缓存系统里对缓存项操作的接口
 5 */
 6interface CacheItemInterface
 7{
 8    /**
 9     * 返回当前缓存项的 `键`
10     *
11     * `键` 由实现类库来加载，并且高层的调用者（如：CacheItemPoolInterface）
12     *  **应该** 能使用此方法来获取到 `键` 的信息。
13     *
14     * @return string
15     * 当前缓存项的 键
16     */
17    public function getKey();
18
19    /**
20     * 凭借此缓存项的 `键` 从缓存系统里面取出缓存项。
21     *
22     * 取出的数据 **必须** 跟使用 `set()` 存进去的数据是一模一样的。
23     *
24     * 如果 `isHit()` 返回 false 的话，此方法必须返回 `null`，需要注意的是 `null` 本来就是一个合法的缓存数据，所以你 **应该** 使用 `isHit()` 方法来辨别到底是 "返回 null 数据" 还是 "缓存里没有此数据"。
25     *
26     * @return mixed
27     * 此缓存项的 `键` 对应的 `值` ，如果找不到的话，返回 `null`
28     */
29    public function get();
30
31    /**
32     * 确认缓存项的检查是否命中。
33     *
34     * 注意: 调用此方法和调用 `get()` 时 **不得** 有先后顺序之分。
35     *
36     * @return bool
37     * 如果缓冲池里有命中的话，返回 `true`，反之返回 `false`
38     */
39    public function isHit();
40
41    /**
42     * 为此缓存项设置 `值`。
43     *
44     * 参数 $value 可以是所有能被 PHP 序列化的数据，序列化的逻辑需要在实现类库里书写。
45     *
46     * @param mixed $value
47     * 将被存储的可序列化的数据。
48     *
49     * @return static
50     * 返回当前对象。
51     */
52    public function set($value);
53
54    /**
55     * 设置缓存项的准确过期时间点。
56     *
57     * @param \DateTimeInterface $expiration
58     *
59     * 过期的准确时间点，过了这个时间点后，缓存项就 **必须** 被认为是过期了的。
60     * 如果明确的传参 `null` 的话，**可以** 使用一个默认的时间。
61     * 如果没有设置的话，缓存 **应该** 存储到底层实现的最大允许时间。
62     *
63     * @return static
64     * 返回当前对象。
65     */
66    public function expiresAt($expiration);
67
68    /**
69     * 设置缓存项的过期时间。
70     *
71     * @param int|\DateInterval $time
72     * 以秒为单位的过期时长，过了这段时间后，缓存项就 **必须** 被认为是过期了的。
73     * 如果明确的传参 `null` 的话，**可以** 使用一个默认的时间。
74     * 如果没有设置的话，缓存 **应该** 存储到底层实现的最大允许时间。
75     *
76     * @return static
77     * 返回当前对象
78     */
79    public function expiresAfter($time);
80
81}

  1namespace Psr\Cache;
  2
  3/**
  4 * CacheItemPoolInterface 生成 CacheItemInterface 对象
  5 */
  6interface CacheItemPoolInterface
  7{
  8    /**
  9     * 返回 `键` 对应的一个缓存项。
 10     *
 11     * 此方法 **必须** 返回一个 CacheItemInterface 对象，即使是找不到对应的缓存项
 12     * 也 **不得** 返回 `null`。
 13     *
 14     * @param string $key
 15     * 用来搜索缓存项的`键`。
 16     *
 17     * @throws InvalidArgumentException
 18     * 如果 $key 不是合法的值，\Psr\Cache\InvalidArgumentException 异常会被抛出。
 19     *
 20     * @return CacheItemInterface
 21     * 对应的缓存项。
 22     */
 23    public function getItem($key);
 24
 25    /**
 26     * 返回一个可供遍历的缓存项集合。
 27     *
 28     * @param array $keys
 29     * 由一个或者多个 `键` 组成的数组。
 30     *
 31     * @throws InvalidArgumentException
 32     * 如果 $keys 里面有哪个`键`不是合法，\Psr\Cache\InvalidArgumentException 异常会被抛出。
 33     *   
 34     *
 35     * @return array|\Traversable
 36     * 返回一个可供遍历的缓存项集合，集合里每个元素的标识符由 `键` 组成，即使即使是找不到对的缓存项，也要返回一个「CacheItemInterface」对象到对应的 `键` 中。
 37     * 如果传参的数组为空，也需要返回一个空的可遍历的集合。
 38     */
 39    public function getItems(array $keys = array());
 40
 41    /**
 42     * 检查缓存系统中是否有 `键` 对应的缓存项。
 43     *
 44     * 注意: 此方法应该调用 `CacheItemInterface::isHit()` 来做检查操作，而不是`CacheItemInterface::get()`
 45     *
 46     * @param string $key
 47     * 用来搜索缓存项的 `键` 。
 48     *
 49     * @throws InvalidArgumentException
 50     * 如果 $key 不是合法的值，\Psr\Cache\InvalidArgumentException 异常会被抛出。
 51     *
 52     * @return bool
 53     * 如果存在 `键` 对应的缓存项即返回 true，否则 false
 54     */
 55    public function hasItem($key);
 56
 57    /**
 58     * 清空缓冲池
 59     *
 60     * @return bool 
 61     * 成功返回 true，有错误发生返回 false
 62     */
 63    public function clear();
 64
 65    /**
 66     * 从缓冲池里移除某个缓存项
 67     *
 68     * @param string $key
 69     * 用来搜索缓存项的 `键` 。
 70     *
 71     * @throws InvalidArgumentException
 72     * 如果 $key 不是合法的值，\Psr\Cache\InvalidArgumentException 异常会被抛出。
 73     *
 74     * @return bool
 75     * 成功返回 true，有错误发生返回 false
 76     */
 77    public function deleteItem($key);
 78
 79    /**
 80     * 从缓冲池里移除多个缓存项
 81     *
 82     * @param array $keys
 83     * 由一个或者多个 `键` 组成的数组。
 84     *
 85     * @throws InvalidArgumentException
 86     * 如果 $keys 里面有哪个 `键` 不是合法，\Psr\Cache\InvalidArgumentException 异常会被抛出。
 87     *
 88     * @return bool
 89     * 成功返回 true，有错误发生返回 false
 90     */
 91    public function deleteItems(array $keys);
 92
 93    /**
 94     * 立刻为「CacheItemInterface」对象做数据持久化。
 95     *
 96     * @param CacheItemInterface $item
 97     * 将要被存储的缓存项
 98     *
 99     * @return bool
100     * 成功返回 true，有错误发生返回 false
101     */
102    public function save(CacheItemInterface $item);
103
104    /**
105     * 稍后为「CacheItemInterface」对象做数据持久化。
106     *
107     * @param CacheItemInterface $item
108     * 将要被存储的缓存项
109     *
110     * @return bool
111     * 成功返回 true，有错误发生返回 false
112     */
113    public function saveDeferred(CacheItemInterface $item);
114
115    /**
116     * 提交所有的正在队列里等待的请求到数据持久层，配合 `saveDeferred()` 使用
117     *
118     * @return bool
119     * 成功返回 true，有错误发生返回 false
120     */
121    public function commit();
122}

1namespace Psr\Cache;
2
3/**
4 * 被所有的实现类库抛出的异常继承的 `异常接口`
5 */
6interface CacheException
7{
8}

 1namespace Psr\Cache;
 2
 3/**
 4 * 传参错误抛出的异常接口
 5 *
 6 * 当一个错误或者非法的传参发生时，**必须** 抛出一个继承了
 7 * Psr\Cache\InvalidArgumentException 的异常
 8 */
 9interface InvalidArgumentException extends CacheException
10{
11}