PSR-16:缓存库的通用接口

缓存库的通用接口

本文档描述了缓存项和缓存驱动程序的简单但可扩展的接口。

本文件中的关键词“必须”,“不得”,“必须”,“应该”,“不应该”,“应该”,“不应该”,“推荐”,“可以”和“可选”按照RFC 2119中的描述进行解释

最终的实现可以使用比提议的功能更多的功能来装饰对象,但是它们必须首先实现所指示的接口/功能。

1.规格

1.1简介

缓存是提高任何项目性能的常用方法,使缓存库成为许多框架和库的最常见功能之一。此级别的互操作性意味着库可以删除自己的缓存实现,并轻松依赖框架或其他专用缓存库给予它们的实现。

PSR-6已经解决了这个问题,但是以一种相当正式和冗长的方式解决了最简单的用例所需要的问题。这种更简单的方法旨在为常见案例构建标准化的简化界面。它独立于PSR-6,但设计为尽可能简单地与PSR-6兼容。

1.2定义

调用库,实现库,TTL,到期和密钥的定义从PSR-6复制,因为相同的假设是正确的。

  • 调用库 - 实际需要缓存服务的库或代码。该库将利用实现此标准接口的缓存服务,但不会知道这些缓存服务的实现。

  • 实现库 - 该库负责实现此标准,以便为任何调用库提供缓存服务。实现库必须提供一个实现Psr \ SimpleCache \ CacheInterface接口的类。实现库必须支持至少TTL功能,如下所述,具有全秒级粒度。

  • TTL - 项目的生存时间(TTL)是该项目存储与被视为陈旧之间的时间量。TTL通常由表示以秒为单位的时间的整数或DateInterval对象定义。

  • 到期 - 项目设置为过时的实际时间。这是通过将TTL添加到存储对象的时间来计算的。

    在1:30:00存储300秒TTL的项目将到期为1:35:00。

    实现库可能会在其请求的到期时间之前使项目到期,但是一旦达到其到期时间,必须将项目视为已过期。如果调用库要求保存项目但未指定过期时间,或指定空过期时间或TTL,则实现库可以使用配置的默认持续时间。如果没有设置默认持续时间,实现库必须将其解释为永久缓存项目的请求,或者只要底层实现支持。

    如果提供了负TTL或零TTL,则必须从缓存中删除该项(如果存在),因为它已经过期。

  • 密钥 - 至少一个字符的字符串,用于唯一标识缓存的项目。实施库必须支持由字符的键A-Za-z0-9_,和.在以UTF-8编码的任何顺序和最多64个字符的长度。实现库可以支持额外的字符和编码或更长的长度,但必须支持至少这个最小值。库负责自己的密钥字符串转义,但必须能够返回原始未修改的密钥字符串。以下字符保留用于将来的扩展,并且实现库不得支持:{}()/\@:

  • 缓存 - 实现Psr\SimpleCache\CacheInterface接口的对象

  • 高速缓存未命中 - 高速缓存未命中将返回null,因此检测是否null存在无法存储的高速缓存这是PSR-6假设的主要偏差。

1.3缓存

实现可以为用户提供一种机制,如果没有为特定的缓存项指定默认TTL,则指定默认TTL。如果没有提供用户指定的默认值,则实现必须默认为底层实现允许的最大合法值。如果底层实现不支持TTL,则必须静默忽略用户指定的TTL。

1.4数据

实现库必须支持所有可序列化的PHP数据类型,包括:

  • 字符串 - 任何PHP兼容编码中任意大小的字符串。
  • 整数 - PHP支持的任何大小的所有整数,最多64位有符号。
  • 花车 -所有签署浮点值。
  • 布尔 - 真与假。
  • Null - 空值(尽管在将其读回时无法与高速缓存未命中区分)。
  • 数组 - 任意深度的索引,关联和多维数组。
  • 对象 - 支持无损序列化和反序列化的任何对象,以便$ o == unserialize(serialize($ o))。对象可以利用PHP的Serializable接口,__sleep()或者__wakeup()魔术方法,或者如果合适的话类似的语言功能。

传递到实现库的所有数据必须完全按照传递的方式返回。这包括变量类型。也就是说,如果(int)5是保存的值则返回(字符串)5是错误的。实现库可以在内部使用PHP的serialize()/ unserialize()函数,但不是必须这样做。与它们的兼容性仅用作可接受对象值的基线。

如果由于任何原因无法返回确切的保存值,则实现库必须以缓存未命中而不是损坏的数据进行响应。

2.接口

2.1 CacheInterface

缓存接口定义了一组缓存条目的最基本操作,这需要基本读取,写入和删除单个缓存项。

此外,它还具有处理多组缓存条目的方法,例如一次写入,读取或删除多个缓存条目。当您需要执行大量高速缓存读/写操作时,这非常有用,并且允许您在一次调用高速缓存服务器时执行操作,从而显着缩短延迟时间。

CacheInterface的实例对应于具有单个键名称空间的单个缓存项集合,并且等同于PSR-6中的“池”。不同的CacheInterface实例可以由相同的数据存储区支持,但必须在逻辑上独立。

<?php

namespace Psr\SimpleCache;

interface CacheInterface
{
    /**
     * Fetches a value from the cache.
     *
     * @param string $key     The unique key of this item in the cache.
     * @param mixed  $default Default value to return if the key does not exist.
     *
     * @return mixed The value of the item from the cache, or $default in case of cache miss.
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   MUST be thrown if the $key string is not a legal value.
     */
    public function get($key, $default = null);

    /**
     * Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time.
     *
     * @param string                 $key   The key of the item to store.
     * @param mixed                  $value The value of the item to store. Must be serializable.
     * @param null|int|\DateInterval $ttl   Optional. The TTL value of this item. If no value is sent and
     *                                      the driver supports TTL then the library may set a default value
     *                                      for it or let the driver take care of that.
     *
     * @return bool True on success and false on failure.
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   MUST be thrown if the $key string is not a legal value.
     */
    public function set($key, $value, $ttl = null);

    /**
     * Delete an item from the cache by its unique key.
     *
     * @param string $key The unique cache key of the item to delete.
     *
     * @return bool True if the item was successfully removed. False if there was an error.
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   MUST be thrown if the $key string is not a legal value.
     */
    public function delete($key);

    /**
     * Wipes clean the entire cache's keys.
     *
     * @return bool True on success and false on failure.
     */
    public function clear();

    /**
     * Obtains multiple cache items by their unique keys.
     *
     * @param iterable $keys    A list of keys that can obtained in a single operation.
     * @param mixed    $default Default value to return for keys that do not exist.
     *
     * @return iterable A list of key => value pairs. Cache keys that do not exist or are stale will have $default as value.
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   MUST be thrown if $keys is neither an array nor a Traversable,
     *   or if any of the $keys are not a legal value.
     */
    public function getMultiple($keys, $default = null);

    /**
     * Persists a set of key => value pairs in the cache, with an optional TTL.
     *
     * @param iterable               $values A list of key => value pairs for a multiple-set operation.
     * @param null|int|\DateInterval $ttl    Optional. The TTL value of this item. If no value is sent and
     *                                       the driver supports TTL then the library may set a default value
     *                                       for it or let the driver take care of that.
     *
     * @return bool True on success and false on failure.
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   MUST be thrown if $values is neither an array nor a Traversable,
     *   or if any of the $values are not a legal value.
     */
    public function setMultiple($values, $ttl = null);

    /**
     * Deletes multiple cache items in a single operation.
     *
     * @param iterable $keys A list of string-based keys to be deleted.
     *
     * @return bool True if the items were successfully removed. False if there was an error.
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   MUST be thrown if $keys is neither an array nor a Traversable,
     *   or if any of the $keys are not a legal value.
     */
    public function deleteMultiple($keys);

    /**
     * Determines whether an item is present in the cache.
     *
     * NOTE: It is recommended that has() is only to be used for cache warming type purposes
     * and not to be used within your live applications operations for get/set, as this method
     * is subject to a race condition where your has() will return true and immediately after,
     * another script can remove it, making the state of your app out of date.
     *
     * @param string $key The cache item key.
     *
     * @return bool
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     *   MUST be thrown if the $key string is not a legal value.
     */
    public function has($key);
}

2.2 CacheException


<?php

namespace Psr\SimpleCache;

/**
 * Interface used for all types of exceptions thrown by the implementing library.
 */
interface CacheException
{
}

2.3 InvalidArgumentException

<?php

namespace Psr\SimpleCache;

/**
 * Exception interface for invalid cache arguments.
 *
 * When an invalid argument is passed, it must throw an exception which implements
 * this interface.
 */
interface InvalidArgumentException extends CacheException
{
}