1. Home
  2. PHP
  3. PSR
  4. 【PHP】PSR-6 Caching Interface（キャッシングインターフェイス）

【PHP】PSR-6 Caching Interface（キャッシングインターフェイス）

  • 公開日
  • 更新日
  • カテゴリ：PSR
  • タグ：PHP,cache,PSR,PSR-6
【PHP】PSR-6 Caching Interface（キャッシングインターフェイス）

PSR（PHP 標準勧告）

  1. 概要
  2. PSR-1 Basic Coding Standard
  3. PSR-3 Logger Interface
  4. PSR-4 Autoloader
  5. PSR-6 Caching Interface
  6. PSR-7 HTTP Message Interface
  7. PSR-11 Container Interface
  8. PSR-12 Extended Coding Style
  9. PSR-13 Hypermedia Links
  10. PSR-15 HTTP Handlers
  11. PSR-16 Simple Cache
  12. PSR-17 HTTP Factories
  13. PSR-18 HTTP Client

https://www.php-fig.org/psr/psr-6/

PSR-6 は、PHP におけるキャッシュ操作（システム・ライブラリ作成）についての標準を策定しています。

キャッシングは、あらゆるプロジェクトのパフォーマンスを向上させるための一般的な方法です。

キャッシングライブラリは、多くのフレームワークやライブラリの最も一般的な機能の 1 つになっています。 これは、多くのライブラリがさまざまなレベルの機能を備えた独自のキャッシングライブラリをロールバックする状況につながります。

これらの違いにより、開発者は必要な機能を提供するかどうかを問わず、複数のシステムを学ばなければなりません。

さらに、キャッシングライブラリの開発者は、限られた数のフレームワークをサポートするか、多数のアダプタクラスを作成するかの選択に直面しています。

PSR-6 に準拠したシステムをキャッシュするための共通インタフェースは、これらの問題を解決します。 ライブラリシステムやフレームワークの開発者は、期待したとおりに機能するキャッシングシステムを利用することができ、それによってキャッシングシステムの開発者は、さまざまな種類のアダプタではなく、単一のインターフェイスセットを実装するだけになります。

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

Contents

  1. 定義
    1. ライブラリの呼び出し
    2. 実装ライブラリ
    3. アイテムの存続時間
    4. 有効期限
    5. キー
    6. キャッシュヒット
    7. キャッシュミス
    8. 遅延キャッシュセーブ
  2. データ
  3. 主な概念
  4. エラーハンドリング
  5. インターフェイス
    1. CacheItemInterface
    2. CacheItemPoolInterface
    3. CacheException
    4. InvalidArgumentException

定義

ライブラリの呼び出し

実際にキャッシュサービスが必要なライブラリまたはコード。このライブラリは、この規格のインタフェースを実装するキャッシングサービスを利用するが、キャッシングサービスの実装に関する知識はない。

実装ライブラリ

このライブラリは、任意の呼び出しライブラリにキャッシングサービスを提供するために、この標準を実装する責任があります。

実装ライブラリは、Cache\CacheItemPoolInterface および Cache\CacheItemInterface インターフェイスを実装するクラスを提供する必要があります。

ライブラリを実装するには、以下に説明する TTL の最小限の機能（1 秒単位）をサポートする必要があります。

アイテムの存続時間

アイテムの存続時間（TTL = Time To Live）は、そのアイテムが保存されてから失効したとみなされるまでの時間。 TTL は通常、秒単位の時間を表す整数、または DateInterval オブジェクトによって定義されます。

有効期限

アイテムが古くなるように設定されている実際の時間。これは、通常、オブジェクトが格納されている時間に TTL を追加することによって計算されますが、DateTime オブジェクトで明示的に設定することもできます。

1:30:00 に格納された 300 秒の TTL を持つアイテムの有効期限は 1:35:00 です。

ライブラリを実装すると、要求された有効期限までにアイテムが期限切れになることがありますが、有効期限に達すると期限切れになるアイテムを処理する必要があります。

呼び出し元のライブラリがアイテムの保存を要求しても、有効期限を指定していないか、有効期限が null または TTL である場合、実装ライブラリは既定の構成時間を使用することがあります。

デフォルト期間が設定されていない場合、実装ライブラリはアイテムを永続的にキャッシュする要求として、または基本的な実装がサポートしている限り、それを解釈する必要があります。

キー

キャッシュされたアイテムを一意に識別する少なくとも 1 つの文字列。

ライブラリを実装するには、文字 A～ Z, a～ z, 0～ 9, _、および～からなるキーをサポートしていなければなりません。

UTF-8 エンコーディングで任意の順序で入力することができ、長さは最大 64 文字です。

ライブラリを実装すると、追加の文字やエンコーディング、長めの長さをサポートすることができますが、少なくともその最小値をサポートする必要があります。

ライブラリは、必要に応じて独自のキー文字列をエスケープしますが、元の変更されていないキー文字列を返すことができる必要があります。

次の文字は将来の拡張用に予約されており、ライブラリを実装することでサポートしてはいけません：{}（）/ \ @：

キャッシュヒット

コール・ライブラリーがキーでアイテムを要求し、そのキーに一致する値が見つかってその値が期限切れになっておらず、値が他の理由で無効でない場合に、キャッシュ・ヒットが発生します。 ライブラリを呼び出すには、すべての get() 呼び出しで isHit() を確認する必要があります。

キャッシュミス

キャッシュミスはキャッシュヒットの逆です。 Calling Library がキーでアイテムを要求し、そのキーにその値が見つからないか、値が見つかったが期限が切れているか、または何らかの理由で値が無効である場合に、キャッシュミスが発生します。 期限切れの値は、常にキャッシュミスとみなされる必要があります。

遅延キャッシュセーブ

遅延キャッシュセーブは、キャッシュアイテムがプールによって直ちに永続化されない可能性があることを示します。

Pool オブジェクトは、一部のストレージエンジンでサポートされているバルクセット操作を利用するために、遅延キャッシュ項目の永続化を遅延させる可能性があります。

プールは、遅延キャッシュ・アイテムが最終的に永続化され、データが失われないことを保証しなければなりません。 呼び出しライブラリが commit() メソッドを呼び出すと、未処理の遅延アイテムはすべて永続化されなければなりません。

実装ライブラリは、オブジェクトデストラクタ、save(), タイムアウトまたは max-items チェック、またはその他の適切なロジックのすべてを永続化するなど、遅延アイテムをいつ保存するかを決定するのに適切なロジックを使用できます。 遅延されたキャッシュ項目に対する要求は、遅延されているがまだ永続化されていない項目を返す必要があります。

データ

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

  • Strings（文字列）
    • PHP 互換の任意のエンコーディングで任意のサイズの文字列。
  • Integers（整数）
    • PHP がサポートする任意のサイズのすべての整数（最大 64 ビット）。
  • Floats（浮動小数点）
    • すべての符号付き浮動小数点値。 BooleanTrue および False 。 Null 実際の null 値。
  • Arrays（配列）
    • 任意の深さのインデックス付き、連想型および多次元配列。
  • Object
    • 以下のようなロスレスシリアル化とデシリアライゼーションをサポートするオブジェクトです。
    • オブジェクトは、PHP の Serializable インターフェイス、__sleep() または__wakeup() のマジックメソッド、または必要に応じて同様の言語機能を利用できます。
$o == unserialize(serialize($o))

実装ライブラリに渡されるすべてのデータは、渡されたとおりに返されなければなりません。これには可変型が含まれます。つまり、if（int） 5 が保存された値だった場合、（string） 5 を返すのはエラーです。ライブラリの実装では、PHP の serialize() / unserialize() 関数を内部的に使用できますが、必須ではありません。それらとの互換性は、許容可能なオブジェクト値のベースラインとして単に使用されます。

何らかの理由で正確に保存された値を返すことができない場合、ライブラリを実装すると、データが破損するのではなくキャッシュミスが返されます。

主な概念

プール

プールは、キャッシュシステム内のアイテムのコレクションを表します。 プールは、それに含まれるすべてのアイテムの論理リポジトリです。 キャッシュ可能なアイテムはすべてプールからアイテムオブジェクトとして取得され、キャッシュされたオブジェクトのユニバース全体とのすべてのやりとりはプールを通じて行われます。

アイテム

アイテムは、プール内の単一のキー/値のペアを表します。 キーはアイテムの一次固有識別子であり、不変でなければなりません。 値はいつでも変更することができます。

エラーハンドリング

  • キャッシングはアプリケーションのパフォーマンスの重要な部分に成り得ますが、決してアプリケーションの機能の重要な部分ではありません。したがって、キャッシュ・システムのエラーでアプリケーションが失敗してはなりません。 このため、インプリメンテーションライブラリは、インタフェースで定義された例外以外の例外をスローしてはならず、基になるデータストアによってトリガされたエラーや例外をトラップし、バブル処理を行わないようにする必要があります。
  • 実装ライブラリは、そのようなエラーを記録するか、適切な場合に管理者に報告する必要があります。
  • 呼び出し側のライブラリが、1 つまたは複数のアイテムを削除するように要求した場合、またはプールをクリアする場合、指定されたキーが存在しない場合、エラー条件とみなしてはなりません。 事後条件は同じです（キーは存在しないかプールは空です）。したがって、エラー状態はありません。

インターフェイス

CacheItemInterface

CacheItemInterface はキャッシュシステム内の項目を定義します。

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

Cache\CacheItemInterface オブジェクトは、キャッシュ項目の格納と取り出しをカプセル化します。 各 Cache\CacheItemInterface は、Cache\CacheItemPoolInterface オブジェクトによって生成されます。このオブジェクトは、必要なセットアップを行い、オブジェクトを一意のキーに関連付けるものです。

Cache\CacheItemInterface オブジェクトは、このドキュメントの「データ」セクションで定義されているすべてのタイプの PHP 値を格納および取得できる必要があります。

ライブラリを呼び出すには、Item オブジェクト自体をインスタンス化する必要があります。 それらは、getItem() メソッドを介してプールオブジェクトからのみ要求されることがあります。

ライブラリを呼び出すには、1 つの実装ライブラリによって作成されたアイテムが別の実装ライブラリからのプールと互換性があると想定する必要があります。

<?php

namespace Psr\Cache;

/**
 * CacheItemInterface
 * キャッシュ内のオブジェクトと対話するためのインターフェイスを定義する
 */
interface CacheItemInterface
{
    /**
     * 現在のキャッシュ項目のキーを返します。
     * キーは実装ライブラリによってロードされますが、
     * 必要に応じて上位の呼び出し元が使用できるようにする必要があります。
     *
     * @return string このキャッシュ項目のキー文字列。
     */
    public function getKey();

    /**
     * このオブジェクトのキーに関連付けられたキャッシュから項目の値を取得します。
     * 返される値は、もともとset（）によって格納された値と同じでなければなりません。
     * isHit（）がfalseを返す場合、このメソッドはnullを返す必要があります。
     * nullは正当なキャッシュされた値なので、
     * "null値が見つかりました"
     * と
     * "値が見つかりませんでした"
     * を区別するためにisHit（）メソッドを使用する必要があります。
     *
     * @return mixed
     *   このキャッシュアイテムのキーに対応する値。見つからない場合はnull
     */
    public function get();

    /**
     * キャッシュ項目検索でキャッシュヒットが発生したかどうかを確認します。
     * 注意：このメソッドは、isHit（）の呼び出しとget（）の呼び出しの間に
     * 競合条件を持つものであってはなりません。
     *
     * @return bool
     *   要求がキャッシュヒットになった場合はtrue。 そうでなければFalse。
     */
    public function isHit();

    /**
     * このキャッシュアイテムによって表される値を設定します。
     * 引数$valueはPHPによってシリアライズできる項目ですが、
     * 直列化の方法はImplementing Libraryに任されています。
     *
     * @param mixed $value
     *   シリアライズ可能な値を格納します。
     *
     * @return static
     *   呼び出されたオブジェクト。
     */
    public function set($value);

    /**
     * このキャッシュ項目の有効期限を設定します。
     *
     * @param \DateTimeInterface|null $expiration
     *   項目が期限切れとみなされる必要がある時点。
     *   nullが明示的に渡された場合、デフォルト値が使用されます。
     *   どれも設定されていない場合、値は永続的に、
     *   または実装が許す限り長く保存する必要があります。
     *
     * @return static
     *   呼び出されたオブジェクト。
     */
    public function expiresAt($expiration);

    /**
     * Sets the expiration time for this cache item.
     *
     * @param int|\DateInterval|null $time
     *   アイテムが期限切れとみなされる必要がある現在からの期間。
     *   整数パラメータは、有効期限までの秒単位の時間と解釈されます。
     *   nullが明示的に渡された場合、デフォルト値が使用されます。
     *   どれも設定されていない場合、値は永続的に、または実装が許す限り長く保存する必要があります。
     *
     * @return static
     *   呼び出されたオブジェクト。
     */
    public function expiresAfter($time);
}

CacheItemPoolInterface

Cache\CacheItemPoolInterface の主な目的は、呼び出しライブラリからキーを受け取り、関連付けられた Cache\CacheItemInterface オブジェクトを返すことです。また、キャッシュコレクション全体との対話の主要なポイントです。

プールのすべての構成と初期化は、実装ライブラリに任せられます。

<?php

namespace Psr\Cache;

/**
 * CacheItemPoolInterface
 * CacheItemInterfaceオブジェクトを生成します。
 */
interface CacheItemPoolInterface
{
    /**
     * 指定されたキーを表すキャッシュ項目を返します。
     * このメソッドは、キャッシュミスの場合でも常に
     * CacheItemInterfaceオブジェクトを返す必要があります。
     * nullを返さないでください。
     *
     * @param string $key
     *   対応するキャッシュ項目を返すキー
     *
     * @throws InvalidArgumentException
     *   $key文字列が正当な値でない場合、
     *   \Psr\Cache\InvalidArgumentException
     *   がスローされなければなりません。
     *
     * @return CacheItemInterface
     *   対応するキャッシュ項目
     */
    public function getItem($key);

    /**
     * トラバース可能なキャッシュ項目のをセット返します。
     *
     * @param string[] $keys
     *   取得する項目のキーのインデックス付き配列
     *
     * @throws InvalidArgumentException
     *   $keysのいずれかのキーが正当な値でない場合、
     *   \Psr\Cache\InvalidArgumentException
     *   がスローされなければなりません。
     *
     * @return array|\Traversable
     *   各アイテムのキャッシュキーによってキーされた
     *   キャッシュアイテムのトラバース可能なコレクション。
     *   そのキーが見つからない場合でも、各キーのキャッシュ
     *   項目が返されます。
     *   ただし、キーが指定されていない場合は、
     *   代わりに空のトラバーサルを返す必要があります。
     */
    public function getItems(array $keys = array());

    /**
     * キャッシュに指定されたキャッシュ項目が含まれているかどうかを確認します。
     *
     * 注意：この方法では、パフォーマンス上の理由からキャッシュされた値を取得
     * することを避けることができます。 これにより、CacheItemInterface::get()
     * との競合状態が発生する可能性があります。
     * このような状況を回避するには、代わりにCacheItemInterface::isHit()を使用します。
     *
     * @param string $key
     *   存在を確認するためのキー
     *
     * @throws InvalidArgumentException
     *   $key文字列が正当な値でない場合
     *   \Psr\Cache\InvalidArgumentException
     *   をスローする必要があります。
     *
     * @return bool
     *   アイテムがキャッシュに存在する場合はtrue、そうでない場合はfalse
     */
    public function hasItem($key);

    /**
     * プール内のすべてのアイテムを削除します。
     *
     * @return bool
     *   プールが正常にクリアされた場合はtrue。
     *   エラーがあった場合はFalseを返します。
     */
    public function clear();

    /**
     * アイテムをプールから削除します。
     *
     * @param string $key
     *   削除するキー
     *
     * @throws InvalidArgumentException
     *   $key文字列が正当な値でない場合
     *   \Psr\Cache\InvalidArgumentException
     *   をスローする必要があります。
     *
     * @return bool
     *   項目が正常に削除された場合はtrue。
     *   エラーがあった場合はFalseを返します。
     */
    public function deleteItem($key);

    /**
     * プールから複数のアイテムを削除します。
     *
     * @param string[] $keys
     *   プールから削除する必要があるキーの配列。
     *
     * @throws InvalidArgumentException
     *   $keysのいずれかのキーが正当な値でない場合、
     *   \Psr\Cache\InvalidArgumentException
     *   がスローされなければなりません。
     *
     * @return bool
     *   アイテムが正常に削除された場合はtrue。
     *   エラーがあった場合はFalseを返します。
     */
    public function deleteItems(array $keys);

    /**
     * キャッシュ項目を保持します。
     *
     * @param CacheItemInterface $item
     *   保存するキャッシュ項目。
     *
     * @return bool
     *   項目が正常に永続化された場合はtrue。
     *   エラーがあった場合はFalseを返します。
     */
    public function save(CacheItemInterface $item);

    /**
     * 後で永続化されるキャッシュ項目を設定します。
     *
     * @param CacheItemInterface $item
     *   保存するキャッシュ項目。
     *
     * @return bool
     *   アイテムがキューに入れられなかった場合、
     *   またはコミットが試行され失敗した場合はFalse。
     *   そうでなければtrue。
     */
    public function saveDeferred(CacheItemInterface $item);

    /**
     * すべての遅延キャッシュ項目を保持します。
     *
     * @return bool
     *   保存されていないアイテムがすべて正常に保存された場合、
     *   または保存されていないアイテムがある場合はTrue。
     *   そうでなければFalse。
     */
    public function commit();
}

CacheException

この例外インターフェイスは、キャッシュサーバーへの接続や無効な資格情報の提供など、キャッシュのセットアップなど、重大なエラーが発生した場合に使用するためのものです。

実装ライブラリによってスローされた例外は、このインタフェースを実装する必要があります。

<?php

namespace Psr\Cache;

/**
 * 実装ライブラリによってスローされる
 * すべての例外に対する例外インタフェース。
 */
interface CacheException
{
}

InvalidArgumentException

<?php

namespace Psr\Cache;

/**
 * 無効なキャッシュ引数の例外インタフェース。
 *
 * 無効な引数がメソッドに渡されると、
 * Psr\Cache\InvalidArgumentException
 * を実装する例外クラスをスローする必要があります。
 */
interface InvalidArgumentException extends CacheException
{
}

Author

rito

  • Backend Engineer
  • Tokyo, Japan
  • PHP 5 技術者認定上級試験　認定者
  • 統計検定 3 級