<?php

namespace Psr\SimpleCache;

interface CacheInterface
{
    /**
     * 从缓存中获取缓存项的值
     *
     * @param string $key     要获取的缓存项目的键
     * @param mixed  $default 如果键指定的缓存项不存在则返回该默认值
     *
     * @return mixed 缓存项的值，如果缓存丢失，则返回传递的默认值
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   如果 $key 非法，则 **必须** 抛出此异常
     */
    public function get($key, $default = null);

    /**
     * 持久化缓存中保存的数据
     *
     * @param string                 $key   要保存的缓存项的键
     * @param mixed                  $value 要保存的缓存项的值，必须是可序列化的
     * @param null|int|\DateInterval $ttl   可选. 当前缓存项的 TTL。
     *                                      如果未指定此值且驱动程序支持 TTL
     *                                      那么库可以设定一个默认值或留给驱动程序自行处理
     *
     * @return bool 成功返回 true ，失败返回 false
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   如果 $key 非法，则 **必须** 抛出此异常
     */
    public function set($key, $value, $ttl = null);

    /**
     * 根据指定的键从缓存中删除缓存项
     *
     * @param string $key 要删除的缓存项的键
     *
     * @return bool 成功返回 true ，如果出错则返回 fasle
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   如果 $key 不是一个合法的值，则 **必须** 抛出此异常
     */
    public function delete($key);

    /**
     * 清空缓存系统
     *
     * @return bool 清空成功返回 true ，失败返回 false 
     */
    public function clear();

    /**
     * 根据指定的键返回多个缓存项
     *
     * @param iterable $keys  单个操作中获取的键的列表
     * @param mixed    $default 如果某个键的值的值不存在，则将此值作为该键的值
     *
     * @return 可迭代的键值对列表. 如果某个键的值不存在，它仍然会使用 $default 作为其志
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   如果 $keys 不是一个数组或一个可迭代对象，或者 $keys 中的任何键非法
     *   则 **必须** 抛出此异常
     */
    public function getMultiple($keys, $default = null);

    /**
     * 持久化一组键值对和可选的 TTL
     *
     * @param iterable               $values 多个键值对的组成的列表
     * @param null|int|\DateInterval $ttl    可选. 当前缓存项的 TTL。
     *                                       如果未指定此值且驱动程序支持 TTL
     *                                       那么库可以设定一个默认值或留给驱动程序自行处理
     *
     * @return bool 成功返回 true，失败返回 false
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   如果 $values 不是一个数组或一个可迭代对象，或者 $values 中的任何键非法
     *   则 **必须** 抛出此异常
     */
    public function setMultiple($values, $ttl = null);

    /**
     * 单次操作中删除多个缓存项
     *
     * @param iterable $keys 要删除的字符串类型的键列表
     *
     * @return bool 如果删除成功返回 true，如果发生错误则返回 false
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   如果 $keys 不是一个数组或一个可迭代对象，或者 $keys 中的任何键非法
     *   则 **必须** 抛出此异常
     */
    public function deleteMultiple($keys);

    /**
     * 判断缓存中是否包含某个数据
     *
     * 注意：建议 has() 方法只用于缓存预处理等用途中且
     * 不要用在实时应用程序中的 get/set 操作，
     * 因为此方法返回 true 的条件会在随后的另一个脚本立即执行的删除操作打破，
     * 使得缓存项的状态立刻过时
     * 
     * @param string $key 缓存数据的键名
     *
     * @return bool
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException 
     * 如果字符串格式的键名 $key 不是合法的值则抛出此异常
     */
    public function has($key);
}

<?php

namespace Psr\SimpleCache;

/**
 *  所有缓存异常的基本接口
 */
interface CacheException
{
}

<?php

namespace Psr\SimpleCache;

/**
 * 缓存参数无效时抛出的异常接口
 *
 * 当传递的缓存参数无效时 **必须** 抛出实现了这个接口的异常
 * this interface
 */
interface InvalidArgumentException extends CacheException
{
}