PSR-6: Интерфейс кэширования

Кэширование - это распространенный способ улучшить производительность любого проекта, что делает библиотеки кеширования одной из наиболее распространенных функций многих фреймворков и библиотек. Это привело к ситуации, когда многие библиотеки используют собственные библиотеки кэширования с различными уровнями функциональности. Эти различия вынуждают разработчиков изучать несколько систем, которые могут или не могут обеспечивать необходимую им функциональность. Кроме того, сами разработчики кэширующих библиотек сталкиваются с выбором между поддержкой только ограниченного числа фреймворков или созданием большого количества классов адаптеров.

Общий интерфейс для систем кэширования решит эти проблемы. Разработчики библиотек и фреймворков могут рассчитывать на то, что системы кэширования будут работать так, как они ожидают, в то время как разработчикам систем кэширования нужно будет реализовать только один набор интерфейсов, а не весь набор адаптеров.

Библиотеки реализующие psr/cache.

Цель

Цель данного PSR - позволить разработчикам создавать библиотеки с учетом кеширования, которые можно интегрировать в существующие платформы и системы без необходимости разработки на заказ.

Определения

• Вызов библиотеки - библиотека или код, который действительно нуждается в службах кеширования. Эта библиотека будет использовать службы кэширования, которые реализуют интерфейсы этого стандарта, но в противном случае не будет знать о реализации этих служб кэширования.

• Реализация библиотеки - эта библиотека отвечает за реализацию этого стандарта, чтобы предоставлять услуги кэширования любой библиотеке вызовов. Библиотека реализации ДОЛЖНА предоставлять классы, реализующие интерфейсы Cache \ CacheItemPoolInterface и Cache \ CacheItemInterface. Реализация библиотек ДОЛЖНА поддерживать минимальную функциональность TTL, как описано ниже, с точностью до секунды.

• TTL - время жизни (TTL) элемента - это промежуток времени между тем, когда этот элемент сохраняется, и считается устаревшим. TTL обычно определяется целым числом, представляющим время в секундах, или объектом DateInterval.

• Истечение срока - фактическое время, когда элемент настроен на то, чтобы стать устаревшим. Обычно это вычисляется путем добавления TTL ко времени, когда объект сохраняется, но также может быть явно установлен с помощью объекта DateTime. Элемент с 300-секундным TTL, сохраненным в 1:30:00, будет иметь срок действия 1:35:00. Реализация библиотек МОЖЕТ истечь элемент до его запрошенного времени истечения срока действия, но ДОЛЖНА рассматривать элемент как истекший после того, как истечет срок его действия. Если вызывающая библиотека запрашивает сохранение элемента, но не указывает время истечения срока действия или указывает нулевое время истечения срока действия или TTL, Реализационная библиотека МОЖЕТ использовать настроенную продолжительность по умолчанию. Если длительность по умолчанию не была установлена, Библиотека реализации ДОЛЖНА интерпретировать это как запрос на кэширование элемента навсегда или до тех пор, пока базовая реализация поддерживает.

• Ключ - строка по крайней мере из одного символа, которая однозначно идентифицирует кэшированный элемент. Реализация библиотеки должен поддерживать ключи , состоящие из символов A-Z, a-z, 0-9, _, и .в любом порядке в UTF-8 кодировке и длиной до 64 символов. Реализуемые библиотеки МОГУТ поддерживать дополнительные символы и кодировки или более длинные символы, но должны поддерживать как минимум этот минимум. Библиотеки несут ответственность за собственное экранирование ключевых строк в зависимости от ситуации, но ДОЛЖНЫ иметь возможность возвращать исходную немодифицированную строку ключей. Следующие символы зарезервированы для будущих расширений и НЕ ДОЛЖНЫ поддерживаться реализующими библиотеками:{}()/\@:

• Попадание - попадание в кеш происходит, когда библиотека вызовов запрашивает элемент по ключу и для этого ключа найдено соответствующее значение, и это значение не истекло, и значение недействительно по какой-либо другой причине. Вызов библиотек СЛЕДУЕТ проверять isHit () на всех вызовах get ().

• Промах - промах в кэше противоположен попаданию в кеш. Промах в кеше происходит, когда вызывающая библиотека запрашивает элемент по ключу и это значение не найдено для этого ключа, или значение было найдено, но срок его действия истек, или значение недействительно по какой-либо другой причине. Значение с истекшим сроком действия ДОЛЖНО всегда считаться промахом в кэше.

• Отложено- Отложенное сохранение кеша указывает, что элемент кеша не может быть сохранен в пуле немедленно. Объект пула МОЖЕТ отложить сохранение отложенного элемента кэша, чтобы воспользоваться преимуществами операций массового набора, поддерживаемых некоторыми механизмами хранения. Пул ДОЛЖЕН гарантировать, что любые отложенные элементы кэша в конечном итоге сохраняются и данные не теряются, и МОЖЕТ сохранять их до того, как вызывающая библиотека запросит их сохранение. Когда вызывающая библиотека вызывает метод commit (), все невыполненные отложенные элементы ДОЛЖНЫ сохраняться. Реализационная библиотека МОЖЕТ использовать любую подходящую логику для определения того, когда следует сохранять отложенные элементы, например деструктор объекта, сохранение всего при save (), проверку тайм-аута или максимального количества элементов или любую другую подходящую логику. Запросы для отложенного элемента кэша ДОЛЖНЫ возвращать отложенный, но еще не сохраненный элемент.

Данные

Реализующие библиотеки ДОЛЖНЫ поддерживать все сериализуемые типы данных PHP, включая:

• Строки - символьные строки произвольного размера в любой PHP-совместимой кодировке.
• Целые числа - все целые числа любого размера, поддерживаемые PHP, вплоть до 64-битной подписи.
• Floats - все значения с плавающей запятой со знаком.
• Логическое значение - Истина и Ложь.
• Null - фактическое нулевое значение.
• Массивы - индексированные, ассоциативные и многомерные массивы произвольной глубины.
• Объект - любой объект, поддерживающий сериализацию и десериализацию без потерь, например $o == unserialize(serialize($o)). Объекты МОГУТ использовать интерфейс PHP Serializable, __sleep()или __wakeup()магические методы, или аналогичные языковые функции, если это необходимо.

Все данные, переданные в Реализационную библиотеку, ДОЛЖНЫ быть возвращены точно в том виде, в котором они были переданы. Это включает тип переменной. То есть возвращать (string) 5, если (int) 5 было сохраненным значением, является ошибкой. Реализация библиотека может использовать РНР serialize()/ unserialize()функцию внутри , но не обязаны это делать. Совместимость с ними просто используется в качестве основы для приемлемых значений объекта.

Если по какой-либо причине невозможно вернуть точное сохраненное значение, реализующие библиотеки ДОЛЖНЫ отвечать промахом в кэше, а не поврежденными данными.

Ключевые идеи

Бассейн

Пул представляет собой набор элементов в системе кэширования. Пул - это логическое хранилище всех содержащихся в нем элементов. Все кэшируемые элементы извлекаются из пула как объект Item, и все взаимодействие со всем юниверсом кэшированных объектов происходит через пул.

Предметы

Элемент представляет собой одну пару ключ / значение в пуле. Ключ является первичным уникальным идентификатором статьи и ДОЛЖЕН быть неизменным. Значение МОЖЕТ быть изменено в любое время.

Обработка ошибок

Хотя кэширование часто является важной частью производительности приложения, оно никогда не должно быть важной частью функциональности приложения. Таким образом, ошибка в системе кэширования НЕ ДОЛЖНА приводить к сбою приложения. По этой причине Реализующие библиотеки НЕ ДОЛЖНЫ генерировать исключения, отличные от тех, которые определены интерфейсом, и ДОЛЖНЫ перехватывать любые ошибки или исключения, вызванные базовым хранилищем данных, и не позволять им пузыриться.

Реализующей библиотеке СЛЕДУЕТ регистрировать такие ошибки или иным образом сообщать о них администратору, если это необходимо.

Если вызывающая библиотека запрашивает удаление одного или нескольких элементов или очистку пула, это НЕ ДОЛЖНО рассматриваться как состояние ошибки, если указанный ключ не существует. Постусловие такое же (ключ не существует или пул пуст), поэтому нет условия ошибки.

Интерфейсы

CacheItemInterface

CacheItemInterface определяет элемент внутри системы кеширования. Каждый объект Item ДОЛЖЕН быть связан с конкретным ключом, который может быть установлен в соответствии с системой реализации и обычно передается Cache\CacheItemPoolInterface объектом.

Cache\CacheItemInterfaceОбъект инкапсулирует хранения и поиска элементов кэша. Каждый из Cache\CacheItemInterfaceних создается Cache\CacheItemPoolInterfaceобъектом, который отвечает за любую требуемую настройку, а также связывает объект с уникальным ключом. Cache\CacheItemInterfaceобъекты ДОЛЖНЫ иметь возможность сохранять и извлекать любой тип значения PHP, определенный в разделе «Данные» этого документа.

Вызывающие библиотеки НЕ ДОЛЖНЫ создавать экземпляры самих объектов Item. Их можно запросить только у объекта Pool с помощью getItem()метода. Вызов библиотек НЕ ДОЛЖЕН предполагать, что элемент, созданный одной реализационной библиотекой, совместим с пулом из другой реализационной библиотеки.

<?php

namespace Psr\Cache;

/**
 * CacheItemInterface defines an interface for interacting with objects inside a cache.
 */
interface CacheItemInterface
{
    /**
     * Returns the key for the current cache item.
     *
     * The key is loaded by the Implementing Library, but should be available to
     * the higher level callers when needed.
     *
     * @return string
     *   The key string for this cache item.
     */
    public function getKey();

    /**
     * Retrieves the value of the item from the cache associated with this object's key.
     *
     * The value returned must be identical to the value originally stored by set().
     *
     * If isHit() returns false, this method MUST return null. Note that null
     * is a legitimate cached value, so the isHit() method SHOULD be used to
     * differentiate between "null value was found" and "no value was found."
     *
     * @return mixed
     *   The value corresponding to this cache item's key, or null if not found.
     */
    public function get();

    /**
     * Confirms if the cache item lookup resulted in a cache hit.
     *
     * Note: This method MUST NOT have a race condition between calling isHit()
     * and calling get().
     *
     * @return bool
     *   True if the request resulted in a cache hit. False otherwise.
     */
    public function isHit();

    /**
     * Sets the value represented by this cache item.
     *
     * The $value argument may be any item that can be serialized by PHP,
     * although the method of serialization is left up to the Implementing
     * Library.
     *
     * @param mixed $value
     *   The serializable value to be stored.
     *
     * @return static
     *   The invoked object.
     */
    public function set($value);

    /**
     * Sets the expiration time for this cache item.
     *
     * @param \DateTimeInterface|null $expiration
     *   The point in time after which the item MUST be considered expired.
     *   If null is passed explicitly, a default value MAY be used. If none is set,
     *   the value should be stored permanently or for as long as the
     *   implementation allows.
     *
     * @return static
     *   The called object.
     */
    public function expiresAt($expiration);

    /**
     * Sets the expiration time for this cache item.
     *
     * @param int|\DateInterval|null $time
     *   The period of time from the present after which the item MUST be considered
     *   expired. An integer parameter is understood to be the time in seconds until
     *   expiration. If null is passed explicitly, a default value MAY be used.
     *   If none is set, the value should be stored permanently or for as long as the
     *   implementation allows.
     *
     * @return static
     *   The called object.
     */
    public function expiresAfter($time);

}

CacheItemPoolInterface

Основная цель Cache \ CacheItemPoolInterface - принять ключ из библиотеки вызовов и вернуть связанный объект Cache \ CacheItemInterface. Это также основная точка взаимодействия со всей коллекцией кешей. Вся настройка и инициализация пула оставлены на усмотрение библиотеки реализации.

<?php

namespace Psr\Cache;

/**
 * CacheItemPoolInterface generates CacheItemInterface objects.
 */
interface CacheItemPoolInterface
{
    /**
     * Returns a Cache Item representing the specified key.
     *
     * This method must always return a CacheItemInterface object, even in case of
     * a cache miss. It MUST NOT return null.
     *
     * @param string $key
     *   The key for which to return the corresponding Cache Item.
     *
     * @throws InvalidArgumentException
     *   If the $key string is not a legal value a \Psr\Cache\InvalidArgumentException
     *   MUST be thrown.
     *
     * @return CacheItemInterface
     *   The corresponding Cache Item.
     */
    public function getItem($key);

    /**
     * Returns a traversable set of cache items.
     *
     * @param string[] $keys
     *   An indexed array of keys of items to retrieve.
     *
     * @throws InvalidArgumentException
     *   If any of the keys in $keys are not a legal value a \Psr\Cache\InvalidArgumentException
     *   MUST be thrown.
     *
     * @return array|\Traversable
     *   A traversable collection of Cache Items keyed by the cache keys of
     *   each item. A Cache item will be returned for each key, even if that
     *   key is not found. However, if no keys are specified then an empty
     *   traversable MUST be returned instead.
     */
    public function getItems(array $keys = array());

    /**
     * Confirms if the cache contains specified cache item.
     *
     * Note: This method MAY avoid retrieving the cached value for performance reasons.
     * This could result in a race condition with CacheItemInterface::get(). To avoid
     * such situation use CacheItemInterface::isHit() instead.
     *
     * @param string $key
     *   The key for which to check existence.
     *
     * @throws InvalidArgumentException
     *   If the $key string is not a legal value a \Psr\Cache\InvalidArgumentException
     *   MUST be thrown.
     *
     * @return bool
     *   True if item exists in the cache, false otherwise.
     */
    public function hasItem($key);

    /**
     * Deletes all items in the pool.
     *
     * @return bool
     *   True if the pool was successfully cleared. False if there was an error.
     */
    public function clear();

    /**
     * Removes the item from the pool.
     *
     * @param string $key
     *   The key to delete.
     *
     * @throws InvalidArgumentException
     *   If the $key string is not a legal value a \Psr\Cache\InvalidArgumentException
     *   MUST be thrown.
     *
     * @return bool
     *   True if the item was successfully removed. False if there was an error.
     */
    public function deleteItem($key);

    /**
     * Removes multiple items from the pool.
     *
     * @param string[] $keys
     *   An array of keys that should be removed from the pool.
     *
     * @throws InvalidArgumentException
     *   If any of the keys in $keys are not a legal value a \Psr\Cache\InvalidArgumentException
     *   MUST be thrown.
     *
     * @return bool
     *   True if the items were successfully removed. False if there was an error.
     */
    public function deleteItems(array $keys);

    /**
     * Persists a cache item immediately.
     *
     * @param CacheItemInterface $item
     *   The cache item to save.
     *
     * @return bool
     *   True if the item was successfully persisted. False if there was an error.
     */
    public function save(CacheItemInterface $item);

    /**
     * Sets a cache item to be persisted later.
     *
     * @param CacheItemInterface $item
     *   The cache item to save.
     *
     * @return bool
     *   False if the item could not be queued or if a commit was attempted and failed. True otherwise.
     */
    public function saveDeferred(CacheItemInterface $item);

    /**
     * Persists any deferred cache items.
     *
     * @return bool
     *   True if all not-yet-saved items were successfully saved or there were none. False otherwise.
     */
    public function commit();
}

CacheException

Этот интерфейс исключений предназначен для использования при возникновении критических ошибок, включая, помимо прочего, настройку кеша, такую ​​как подключение к серверу кеша или предоставление неверных учетных данных.

Любое исключение, созданное Реализующей библиотекой, ДОЛЖНО реализовывать этот интерфейс.

<?php

namespace Psr\Cache;

/**
 * Exception interface for all exceptions thrown by an Implementing Library.
 */
interface CacheException
{
}

InvalidArgumentException

<?php

namespace Psr\Cache;

/**
 * Exception interface for invalid cache arguments.
 *
 * Any time an invalid argument is passed into a method it must throw an
 * exception class which implements Psr\Cache\InvalidArgumentException.
 */
interface InvalidArgumentException extends CacheException
{
}

Начиная с  версии 2.0 psr / cache , вышеупомянутые интерфейсы были обновлены для добавления подсказок типа аргумента. Начиная с  psr/cache , вышеупомянутые интерфейсы были обновлены для добавления подсказок типа возвращаемого значения. Ссылки array|\Traversableнеобходимо заменить на iterable.