目次

PSR-6: Caching Interface

— y2sunlight 2020-05-19

本章は、若干の補足を加筆してはいるものの単にPSRのサイトを日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。

関連記事

PSR-6: キャッシングインターフェイス

— 原文より翻訳 PSR-6: Caching Interface 2020-04-28 現在

キャッシングは、プロジェクトのパフォーマンスを向上させる一般的な方法であり、キャッシングライブラリは多くのフレームワークとライブラリの最も一般的な機能の1つです。これにより、多くのライブラリが、さまざまなレベルの機能を備えた独自のキャッシュライブラリを動かし始める( roll )状況になりました。これらの違いにより、開発者が必要としている機能を提供いるか否かは別にして、複数のシステムを学習しなげればならない原因を引き起こしました。さらに、キャッシュライブラリの開発者は、限られた数のフレームワークのみをサポートするか、多数のアダプタークラスを作成するかの選択に直面しています。

キャッシングシステムの共通インターフェイスはこれらの問題を解決します。これによりライブラリとフレームワークの開発者は、キャッシングシステムが期待どおりに機能することを期待できます。同時に、キャッシングシステムの開発者は、さまざまなアダプターではなく、単一のインターフェイスセットを実装しなければならないだけです。

このドキュメントのキーワード MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , SHOULD NOT , RECOMMENDED , MAY 及び OPTIONAL は、 RFC 2119で説明されているように解釈して下さい。

RFC 2119の説明
MUST, REQUIRED, SHALL — 絶対必要
MUST NOT, SHALL NOT — 絶対禁止
SHOULD, RECOMMENDED — 推奨（但し、無視できる特定の正当な理由が存在するかもしれない）
SHOULD NOT — 推奨できない（但し、許可できる特定の正当な理由が存在するかもしれない）
MAY, OPTIONAL — オプション


目標

このPSRの目標は、開発者がカスタム開発を必要とせずに既存のフレームワークおよびシステムに統合できるキャッシュ対応ライブラリを作成できるようにすることです。


定義


データ

Implementing library の実装は、以下を含むすべてのシリアライズ可能なPHPデータ型をサポートする必要があります (MUST)。

Implementing Library に渡されるすべてのデータは、渡されたとおりに返される必要があります (MUST)。それには変数の型も含まれます。つまり、(int)5 が保存された値である場合、(string)5 を返すのはエラーです。ライブラリの実装では、PHPのserialize() / unserialize() 関数を内部で使用できますが (MAY)、必須ではありません。それらとの互換性は、許すことができるオブジェクト値の基準として単に使用されます。

なんらかの理由で正確に保存された値を返すことができない場合、Implementing library は、破損したデータではなくキャッシュミスで応答する必要があります (MUST)。


主要な概念

プール

プールは、キャッシュシステム内のアイテムのコレクションを表します。プールは、プールに含まれるすべてのアイテムの論理リポジトリです。 キャッシュ可能なすべてのアイテムはプールからアイテムオブジェクトとして取得され、オブジェクトがキャッシュされたている全世界との対話は全てプールを介して行われます。


アイテム

アイテムは、プール内の単一のキー/値ペアを表します。キーは、アイテムの主要な一意の識別子であり、不変である必要があります (MUST)。 値はいつでも変更できます (MAY)。


エラー処理

キャッシングは多くの場合、アプリケーションのパフォーマンスの重要なパーツですが、アプリケーション機能の不可欠なパーツであってはなりません。従って、キャッシュシステムでエラーが発生しても、アプリケーション障害にするべきではありません (SHOULD NOT)。 そのため、Implementing Library は、インターフェースで定義されたもの以外の例外をスローしてはならず (MUST NOT)、基礎となるデータストアによってトリガーされたエラーまたは例外をトラップしてバブルにしないようにすべきです (SHOULD)。

Implementing Library は、そのようなエラーをログに記録するか、必要に応じて管理者に報告するべきです (SHOULD)。

Calling Library が1つ以上のアイテムの削除、またはプールのクリアを要求する場合、指定されたキーが存在しない場合、エラー状態と見なしてはなりません (MUST NOT)。事後状態は同じ（キーが存在しないか、プールが空）なのでエラー状態ではありません。


インターフェース

CacheItemInterface

CacheItemInterface は、キャッシュシステム内のアイテムを定義します。各アイテムオブジェクトは特定のキーに関連付けられている必要があります。これは実装システムに従って設定でき、通常は Cache\CacheItemPoolInterface オブジェクトによって渡されます。

Cache\CacheItemInterface オブジェクトは、キャッシュアイテムの入出庫をカプセル化します。 個々の Cache\CacheItemInterface は Cache\CacheItemPoolInterface オブジェクトによって生成されます。このオブジェクトは、必要な設定に責任を負い、オブジェクトを一意のキーに関連付けます。 Cache\CacheItemInterface オブジェクトは、本ドキュメントのデータセクションで定義されている任意のタイプのPHP値を保存と取得できる必要があります (MUST)。

Calling Library は、アイテムオブジェクト自体をインスタンス化してはなりません (MUST NOT)。それらは、getItem() メソッドを介してプールオブジェクトからのみ要求できます。Calling Library は、ある Implementing Library によって作成されたアイテムが別の Implementing Library のプール と互換性があるとは想定しないでください (SHOULD NOT)。

メソッド要約
getKey():string現在のキャッシュアイテムのキーを返します。
get():mixedこのオブジェクトのキーに関連付けられたキャッシュからアイテムの値を取得します。
isHit():boolキャッシュアイテムの検索結果がキャッシュヒットになったかどうかを確認します。
set($value):staticこのキャッシュアイテムが表す値を設定します。
expiresAt($expiration):staticこのキャッシュアイテムの有効期限を設定します。
expiresAfter($time):staticこのキャッシュアイテムの有効期間を設定します。
($timeは現時点からの期間です)		 
<?php
 
namespace Psr\Cache;
 
/**
 * CacheItemInterface defines an interface for interacting with objects inside a cache.
 * CacheItemInterfaceは、キャッシュ内のオブジェクトと対話するためのインターフェースを定義します
 */
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().
     * 返される値は、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."
     * 
     * isHit()がfalseを返す場合、このメソッドはnullを返す必要があります。nullは正当なキャッシュ値で
     * あるため、isHit()メソッドを使用して「null値が見つかった」場合と「値が見つからなかった」場合を
     * 区別する必要があります。
     *
     * @return mixed
     *   The value corresponding to this cache item's key, or null if not found.
     *   このキャッシュアイテムのキーに対応する値。見つからない場合はnull。
     */
    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().
     * 
     * 注：このメソッドは、isHit()の呼び出しとget()の呼び出しの間に競合状態があってはなりません。
     *
     * @return bool
     *   True if the request resulted in a cache hit. False otherwise.
     *   リクエストがキャッシュヒットになった場合はtrue。 それ以外の場合はfalse。
     */
    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.
     * 
     * $value引数は、PHPでシリアル化できる任意のアイテムですが、
     * シリアル化の方法は実装ライブラリに委ねられています。
     *
     * @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.
     * 
     *   アイテムが期限切れと見なされる時刻。
     *   nullが明示的に渡される場合、デフォルト値が使用される場合があります。 
     *   デフォルト値に何も設定されていない場合、値は永続的に、または実装が許す限り保存する必要があります。
     *
     * @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.
     * 
     *   現在からのアイテムが期限切れと見なされなければならない期間。
     *   整数パラメータは、有効期限が切れるまでの秒数です。 
     *   nullが明示的に渡される場合、デフォルト値が使用される場合があります。
     *   デフォルト値に何も設定されていない場合、値は永続的に、または実装が許す限り保存する必要があります。
     *
     * @return static
     *   The called object.
     *   呼び出されたオブジェクト。
     */
    public function expiresAfter($time);
 
}


CacheItemPoolInterface

Cache\CacheItemPoolInterface の主な目的は、Calling Library からキーを受け取り、関連付けられた Cache\CacheItemInterface オブジェクトを返すことです。また、キャッシュコレクション全体との相互作用も主要なポイントです。プールのすべての構成と初期化は、Implementing Library に任されています。

メソッド要約
getItem($key)指定されたキーを表すキャッシュアイテムを返します。
getItems(array $keys = array())走査可能(Traversable)なキャッシュアイテムのセットを返します。
hasItem($key)キャッシュに指定されたキャッシュアイテムが含まれているかどうかを確認します。
clear()プール内のすべてのアイテムを削除します。
deleteItem($key)プールからアイテムを削除します。
deleteItems(array $keys)プールから複数のアイテムを削除します。
save(CacheItemInterface $item)キャッシュアイテムをすぐに永続化します。
saveDeferred(CacheItemInterface $item)キャッシュアイテムを後で永続化するように設定します
commit()延期されたキャッシュアイテムを永続化します 
<?php
 
namespace Psr\Cache;
 
/**
 * CacheItemPoolInterface generates CacheItemInterface objects.
 * CacheItemPoolInterfaceはCacheItemInterfaceオブジェクトを生成します。
 */
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.
     * 
     * このメソッドは、キャッシュミスの場合でも、常にCacheItemInterfaceオブジェクトを
     * 返す必要があります。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.
     * 
     *   $key文字列が有効な値でない場合は、\Psr\Cache\InvalidArgumentExceptionを
     *   スローする必要があります。
     *
     * @return CacheItemInterface
     *   The corresponding Cache Item.
     *   対応するキャッシュアイテム
     */
    public function getItem($key);
 
    /**
     * Returns a traversable set of cache items.
     * 走査可能(Traversable)なキャッシュアイテムのセットを返します。
     *
     * @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.
     * 
     *   $keysのいずれかのキーが有効な値ではない場合、\Psr\Cache\InvalidArgumentExceptionを
     *   スローする必要があります。
     *
     * @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.
     * 
     * 注：このメソッドは、パフォーマンス上の理由から、キャッシュされた値の取得を回避する
     * 場合があります。これにより、CacheItemInterface::get()で競合状態が発生する可能性があります。 
     * このような状況を回避するには、代わりに CacheItemInterface::isHit() を使用します。
     *
     * @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.
     * 
     *   $key文字列が有効な値でない場合は、\Psr\Cache\InvalidArgumentExceptionを
     *   スローする必要があります。
     *
     * @return bool
     *   True if item exists in the cache, false otherwise.
     *   アイテムがキャッシュに存在する場合はtrue、それ以外の場合はfalse。
     */
    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.
     *   プールが正常にクリアされた場合はtrue。エラーがあった場合はFalse。
     */
    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.
     * 
     *   $key文字列が有効な値でない場合は、\Psr\Cache\InvalidArgumentExceptionを
     *   スローする必要があります。
     *
     * @return bool
     *   True if the item was successfully removed. False if there was an error.
     *   アイテムが正常に削除された場合はtrue。エラーがあった場合はFalse。
     */
    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.
     * 
     *   $keysのいずれかのキーが有効な値ではない場合、\Psr\Cache\InvalidArgumentException を
     *   スローする必要があります。
     *
     * @return bool
     *   True if the items were successfully removed. False if there was an error.
     *   アイテムが正常に削除された場合はtrue。 エラーがあった場合はFalse。
     */
    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.
     *   アイテムが正常に保持された場合はTrue。エラーがあった場合はFalse。
     */
    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.
     * 
     *   アイテムをキューに入れることができなかった場合、またはコミットが試行されて
     *   失敗した場合はfalse。そうでなければ真
     */
    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.
     * 
     *   まだ保存されていないすべてのアイテムが正常に保存されたか、何もなかった場合はTrue。 
     *   それ以外の場合はfalse。
     */
    public function commit();
}


CacheException

この例外インターフェイスは、重大なエラーが発生した場合に使用することを目的としています。これらのエラーには、キャッシュサーバーへの接続や提供された無効な資格情報などのキャッシュセットアップを含みますが、これらに限定されません。

Implementing Library によってスローされるすべての例外は、このインターフェイスを実装する必要があります (MUST)。 

<?php
 
namespace Psr\Cache;
 
/**
 * Exception interface for all exceptions thrown by an Implementing Library.
 * Implementing Library によってスローされたすべての例外の Exception インターフェース
 */
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.
 *
 * 無効な引数がメソッドに渡されるたびに、Psr\Cache\InvalidArgumentException を実装する例外クラスを
 * スローする必要があります。
 */
interface InvalidArgumentException extends CacheException
{
}