— y2sunlight 2020-05-19

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

関連記事

• PSR - PHP標準勧告
• PSR-1: Basic Coding Standard - 基本コーディング規約
• PSR-3: Logger Interface - ロガーインターフェイス
• PSR-4: Autoloading Standard - オートローディング規約
• PSR-5: PHPDoc Standard(Draft) - PHPDoc規約
• PSR-6: Caching Interface - キャッシングインターフェイス
• PSR-7: HTTP Message Interface - HTTPメッセージインターフェイス
• PSR-11: Container Interface - コンテナインターフェイス
• PSR-12: Extended Coding Style - 拡張コーディングスタイル
• PSR-13: Link definition interfaces - リンク定義インターフェース
• PSR-14: Event Dispatcher - イベントディスパッチャー
• PSR-15: HTTP Server Request Handlers - HTTPサーバーリクエストハンドラー
• PSR-16: Common Interface for Caching Libraries - キャッシングライブラリのための共通インターフェース
• PSR-17: HTTP Factories - HTTPファクトリー
• PSR-18: HTTP Client - HTTPクライアント
• PSR-19: PHPDoc tags(Draft) - PHPDocタグ

— 原文より翻訳 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の目標は、開発者がカスタム開発を必要とせずに既存のフレームワークおよびシステムに統合できるキャッシュ対応ライブラリを作成できるようにすることです。

• Calling Library – 実際にキャッシュサービスを必要とするライブラリまたはコード。このライブラリは、本規約のインターフェースを実装するキャッシングサービスを利用しますが、その他のキャッシングサービスの実装に関する知識は必要ありません。
  
  
• Implementing Library – Calling Library にキャッシングサービスを提供するために、このライブラリは本規約を実装する責任があります。Implementing Library は、Cache\CacheItemPoolInterface および Cache\CacheItemInterface インターフェースを実装するクラスを提供する必要があります (MUST)。Implementing Libraries では、1秒単位で 以下に説明するように、最小限のTTL (Time To Live) 機能をサポートする必要があります (MUST)。
  
  
• TTL – アイテムの残存期間（TTL：Time To Live）は、そのアイテムが保存されてから古くなったと見なされるまでの時間のことです。TTL は通常、秒単位の時間を表す整数、または DateInterval オブジェクトによって定義されます。
  
  
• 有効期限 – アイテムが古くなったと設定される実際の時間。これは通常、オブジェクトが格納された時刻に TTL を加算することで計算されますが、DateTime オブジェクトで明示的に設定することもできます。 300秒の TTL を持つアイテムが 1:30:00 に保存された時、その有効期限は 1:35:00 です。Implementing Library は、要求された有効期限の前にアイテムを期限切れにすることができます (MAY)。ただし、有効期限に達したら、アイテムは期限切れとして扱う必要があります　(MUST)。Calling Library はアイテムの保存を要求しますが、有効期限を指定しない場合、または有効期限または TTL を null に指定した場合、Implementing Library は、構成されたデフォルトの期間を使用してもかまいません (MAY)。 デフォルトの期間が設定されていない場合、Implementing Library は、それを、アイテムを永久に（または基本となる実装がサポートしている限りの間）キャッシュする要求として、それを解釈する必要があります (MUST)。
  
  
• キー – キャッシュされたアイテムを一意に識別する少なくとも1つの文字の文字列。Implementing Library は UTF-8 エンコードで最大 64 文字の長さで任意の順序の文字、A 〜 Z、a 〜 z、0 〜 9、アンダースコア(_)、およびピリオド(.) の文字で構成されるキーをサポートする必要があります (MUST)。Implementing Library は、追加の文字とエンコーディング または より長い文字長をサポートする場合がありますが (MAY)、少なくともその最小値をサポートしなければなりません。ライブラリは、必要に応じてキー文字列の独自のエスケープに責任がありますが、変更されていない元のキー文字列を返すことができる必要があります (MUST)。 次の文字は、将来の拡張のために予約されており、Implementing Library によってサポートしてはなりません (MUST NOT)：{}()/\@:
  
  
• ヒット – キャッシュヒットは、Calling Library がキーでアイテムを要求し、そのキーに一致する値が見つかり、その値が期限切れになっておらず、そして他の理由で値が無効でない場合に発生します。Calling Library は、すべての get() 呼び出しで isHit() による確認をすべきです (SHOULD)。
  
  
• ミス – キャッシュミスは、キャッシュヒットの反対です。キャッシュミスは、Calling Library がキーでアイテムを要求し、そのキーの値が見つからない場合、値が見つかったが有効期限が切れている場合、またはその他の理由で値が無効な場合に発生します。 期限切れの値は、常にキャッシュミスと見なされる必要があります (MUST)。
  
  
• 遅延 – 遅延キャッシュ保存は、キャッシュアイテムがプールによってすぐには保存されない可能性があることを示します。いくつかのストレージエンジンでサポートされている一括設定操作を利用するために、プールオブジェクトは遅延キャッシュアイテムの永続化を遅延させる場合があります (MAY)。プールは、遅延キャッシュアイテムが最終的に永続化され、データが失われないことを確認する必要があります (MUST)。また、Calling Library が永続化を要求する前にそれらを永続化できます (MAY)。Calling Library が commit() メソッドを呼び出す場合、すべての未処理の遅延アイテムを永続化する必要があります (MUST)。Implementing Library は、遅延アイテムを永続化するタイミングを決定するために適切なロジックを使用できます (MAY)。 それは、オブジェクトデストラクタ、save() または タイムアウト または 最大アイテムスチェック時の全ての永続化、その他の適切なロジックです。遅延されているキャッシュアイテムに対する要求は、遅延されまだ永続化されていないアイテムを返す必要があります (MUST)。

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

• Strings – PHP互換エンコーディングの任意のサイズの文字列
  
  
• Integers – 符号付きの64ビットまでのPHPでサポートされている任意のサイズのすべての整数
  
  
• Floats – すべての符号付き浮動小数点値
  
  
• Boolean – TrueおよびFalse
  
  
• Null – 実際のnull値
  
  
• Arrays – 添字配列、連想配列 および 任意の深さの多次元配列
  
  
• Object – $o == unserialize(serialize($o)) のような、無損失性のシリアライゼーションとデシリアライゼーションをサポートするオブジェクト。オブジェクトは、PHPの Serializable インターフェース、__sleep() または__wakeup() マジックメソッド、または必要に応じて同様の言語機能を活用する場合があります(MAY)

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 は、キャッシュシステム内のアイテムを定義します。各アイテムオブジェクトは特定のキーに関連付けられている必要があります。これは実装システムに従って設定でき、通常は 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)。

<?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);
 
}

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

<?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();
}

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

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

<?php
 
namespace Psr\Cache;
 
/**
 * Exception interface for all exceptions thrown by an Implementing Library.
 * Implementing Library によってスローされたすべての例外の Exception インターフェース
 */
interface CacheException
{
}

<?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
{
}