<?php

namespace Psr\Cache;

/**
 * CacheItemInterface 定义了一个用于与缓存内的对象进行交互的接口
 */
interface CacheItemInterface
{
    /**
     * 返回当前缓存项的键
     *
     * 键由实现库加载，但在需要时应提供给更高级别的调用者
     *
     * @return string 当前缓存项的键
     */
    public function getKey();

    /**
     *
     * 根据关联的对象的键从缓存中获取项目 ( item ) 的值
     *
     * 返回的值 **必须** 和调用 `set()` 方法保存时传递的值相同
     *
     * 如果 `isHit()` 返回 false，该方法 **必须** 返回 null。
     * 注意： null 是合法的缓存值，可以使用 `isHit()` 方法来区分 "找到了一个 null 值" 和 "找不到值"
     *
     * 
     * @return mixed
     *   与当前缓存项的键相对应的值，如果未找到，则返回 null
     */
    public function get();

    /**
     * Confirms if the cache item lookup resulted in a cache hit.
     *
     * 确认查找缓存项的结果是否为缓存命中
     *
     * 注意：传递给此方法的条件 **必须** 和传递给 `get()` 方法的条件一样
     *
     * @return bool
     *   如果请求的结果是缓存命中则返回 true ，否则返回 false
     */
    public function isHit();

    /**
     * 保存此缓存项的值
     *
     *
     * $value 参数可以是任何可以被 PHP 序列化的项目，序列化的方法由实现库自己自由决定
     *
     * @param mixed $value 需要被存储的可序列化的值
     *
     * @return static 调用的对象
     */
    public function set($value);

    /**
     * 为此缓存项设置过期时间
     *
     * @param \DateTimeInterface|null $expiration
     * 该时间点之后该项目必须被视为过期。
     * 如果显式传递 null，表示可以使用默认值。
     * 如果没有设置，值应该永久存储或实现类库自己决定
     *
     * @return static 调用对象
     *   The called object.
     */
    public function expiresAt($expiration);

    /**
     * 为此缓存项设置过期时间
     *
     * @param int|\DateInterval|null $time
     * 从当前时间起该项目必须被视为过期的时间段。
     * 整数参数被视为以秒为单位的时间，直到过期。 
     * 如果显式传递 null，可以使用默认值。
     * 如果没有设置，值应该永久存储或实现类库自己决定
     *
     * @return static 调用对象
     */
    public function expiresAfter($time);

}

<?php

namespace Psr\Cache;

/**
 * CacheItemPoolInterface 生成 CacheItemInterface 对象
 */
interface CacheItemPoolInterface
{
    /**
     * 根据指定的键返回一个缓存项 ( Cache Item )
     *
     * 此方法 **必须** 始终返回一个 CacheItemInterface 对象，
     * 即使是缓存丢失，也 **绝对不能** 返回 null
     *
     * @param string $key
     *  要返回的缓存项的键
     *
     * @throws InvalidArgumentException
     *   如果 $key 不是一个合法的值，
     *   则 **必须** 抛出 \Psr\Cache\InvalidArgumentException 异常
     *
     * @return CacheItemInterface
     *   相应的缓存项
     */
    public function getItem($key);

    /**
     * 返回一组可遍历的缓存项
     *
     * @param string[] $keys
     *   要检索的项目的键的组成的索引数组
     *
     * @throws InvalidArgumentException
     *   如果其中的任意某个键不是一个合法的值，
     *   则 **必须** 抛出 \Psr\Cache\InvalidArgumentException 异常
     *
     * @return array|\Traversable
     *   由传递的每个键关联的的缓存项目组成的可遍历集合。
     *   每个键都会返回一个缓存项，即使没有找到该键对应的项。
     *   但是，如果没有指定任何键，则必须返回一个空的可遍历的对象。
     */
    public function getItems(array $keys = array());

    /**
     * 确认缓存系统是否包含指定的缓存项目
     *
     * 注意：出于性能原因，此方法 **可以** 避免检索缓存的值。 
     * 这可能会导致相同的条件下，与 `CacheItemInterface::get()` 的结果不一样 ( 是否存在 )
     * 为了避免这种情况，可以使用 `CacheItemInterface::isHit()` 代替
     *
     * 
     * @param string $key
     *   要检查的键
     *
     * @throws InvalidArgumentException
     *   如果 $key 不是一个合法的值，则 **必须** 抛出 \Psr\Cache\InvalidArgumentException 异常
     *
     * @return bool
     *   如果缓存中存在项目，返回 true ，否则返回 false
     */
    public function hasItem($key);

    /**
     * 清空缓存池
     *
     * @return bool
     *   如果缓存池成功清空返回 true，否则返回 false
     */
    public function clear();

    /**
     * 从缓冲池里移除某个缓存项
     *
     * @param string $key
     *   要删除的缓存项的键名
     *
     * @throws InvalidArgumentException
     *   如果 $key 非法，则 **必须** 抛出 \Psr\Cache\InvalidArgumentException 异常
     *
     * @return bool
     *   成功返回 true，有错误发生返回 false
     */
    public function deleteItem($key);

    /**
     * 从缓存池中删除多个缓存项
     *
     * @param string[] $keys
     *   要删除的缓存项的键名组成的数组

     * @throws InvalidArgumentException
     *   如果 $key 中的任何一个值不合法，则 **必须** 抛出 \Psr\Cache\InvalidArgumentException 异常
     *
     * @return bool
     *   成功返回 true，有错误发生返回 false
     */
    public function deleteItems(array $keys);

    /**
     * 立即持久化 「CacheItemInterface」对象
     *
     * @param CacheItemInterface $item
     *   将要被存储的缓存项
     *
     * @return bool
     *   如果缓存项成功被持久化则返回 true，其它情况返回 false
     */
    public function save(CacheItemInterface $item);

    /**
     * 延迟持久化 「CacheItemInterface」对象
     *
     * @param CacheItemInterface $item
     *   将要被存储的缓存项
     *
     * @return bool
     *   如果缓存项加入队列失败或尝试一个提交操作失败则返回 False，其它情况返回 true
     */

    public function saveDeferred(CacheItemInterface $item);

    /**
     * 提交所有的正在队列里等待的请求到数据持久层，配合 `saveDeferred()` 使用
     *
     * @return bool
     *   成功返回 true，有错误发生返回 false
     */
    public function commit();
}

<?php

namespace Psr\Cache;

/**
 * 缓存异常接口，实现类库抛出的所有异常的根接口
 *
 */
interface CacheException
{
}

<?php

namespace Psr\Cache;

/**
 * 无效缓存参数的异常接口
 *
 * 任何时候，一个无效参数传递到方法时，必须抛出一个实现了
 * Psr\Cache\InvalidArgumentException 的异常类。
 * 
 */
interface InvalidArgumentException extends CacheException
{
}