【PHP】PSR-16 Simple Cache～ライブラリをキャッシュするための共通インタフェース～

---

PSR（PHP 標準勧告）

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

---

PSR-16 では、キャッシュアイテムとキャッシュドライバのためのシンプルで拡張可能なインターフェイスについて定義します。

最終的な実装は提案されたものより多くの機能でオブジェクトを装飾するかもしれませんが、最初に示されたインタフェース/機能を実装しなければなりません。

Contents

1. キャッシング
2. 定義
   1. ライブラリを呼び出す
   2. ライブラリの実装
   3. TTL
   4. 有効期限
   5. キー
   6. キャッシュ
   7. キャッシュミス
3. キャッシュ
4. データ
5. CacheInterface
6. CacheException
7. InvalidArgumentException

キャッシング

キャッシングは、あらゆるプロジェクトのパフォーマンスを向上させるための一般的な方法です。キャッシングライブラリは、多くのフレームワークやライブラリの最も一般的な機能の 1 つになっています。 このレベルの相互運用性は、ライブラリが独自のキャッシング実装を落とし、フレームワークまたは別の専用キャッシュライブラリによって与えられたキャッシング実装に簡単に依存できることを意味します。

PSR-6 はすでにこの問題を解決していますが、もっとも簡単なユースケースに必要なものについては、正式で冗長な方法で解決します。 この簡単なアプローチは、一般的なケースのための標準化された合理化されたインターフェイスを構築することを目指しています。 PSR-6 とは独立していますが、PSR-6 との互換性を可能な限り簡単にするように設計されています。

定義

ライブラリの呼び出し、ライブラリの実装、TTL, 有効期限およびキーの定義は、同じ前提条件が満たされているため、PSR-6 からコピーされます。

ライブラリを呼び出す

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

ライブラリの実装

このライブラリは、任意の呼び出しライブラリにキャッシングサービスを提供するためにこの標準を実装する責任があります。 実装ライブラリは、Psr\SimpleCache\CacheInterface インターフェイスを実装するクラスを提供する必要があります。 ライブラリを実装するには、次に説明する TTL の最小限の機能（1 秒単位）をサポートする必要があります。

TTL

アイテムの存続可能時間（TTL）は、そのアイテムが保存されて間もないとみなされるまでの時間です。 TTL は通常、秒単位の時間を表す整数、または DateInterval オブジェクトによって定義されます。

有効期限

項目が古くなるように設定されている実際の時刻。 これは、オブジェクトが格納されている時間に TTL を加算することによって計算されます。

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

ライブラリを実装すると、リクエストされた有効期限までにアイテムが期限切れになることがありますが、有効期限に達すると期限切れになるアイテムを処理する必要があります。 呼び出し元のライブラリがアイテムの保存をリクエストしても、有効期限を指定していないか、有効期限が null または TTL である場合、実装ライブラリは既定の構成時間を使用することがあります。 デフォルト期間が設定されていない場合、実装ライブラリはアイテムを永続的にキャッシュするリクエストとして、または基本的な実装がサポートしている限り、それを解釈する必要があります。

負の TTL またはゼロの TTL が指定されている場合は、アイテムがすでに期限切れになっているので、キャッシュからアイテムを削除する必要があります。

キー

キャッシュされたアイテムを一意に識別する少なくとも 1 つの文字列。 ライブラリを実装するには、文字 A～ Z, a～ z, 0～ 9, _からなるキーをサポートしていなければなりません。 UTF-8 エンコーディングで任意の順序で入力することができ、長さは最大 64 文字です。

ライブラリを実装すると、追加の文字やエンコーディング、長めの長さをサポートすることができますが、少なくともその最小値をサポートする必要があります。 ライブラリは、必要に応じてキー文字列をエスケープする責任がありますが、元の変更されていないキー文字列を返すことができなければなりません。

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

キャッシュ

Psr\SimpleCache\CacheInterface インターフェイスを実装するオブジェクトです。

キャッシュミス

キャッシュミスは null を返します。

キャッシュ

実装は、特定のキャッシュ項目に対して指定されていない場合、ユーザーがデフォルトの TTL を指定するためのメカニズムを提供することがあります。ユーザー指定のデフォルトが指定されていない場合、実装は、基本となる実装で許可されている最大正当な値にデフォルト設定する必要があります。 基本となる実装が TTL をサポートしていない場合は、ユーザ指定の TTL を暗黙のうちに無視する必要があります。

データ

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

• String（文字列）
  • PHP 互換の任意のエンコーディングで任意のサイズの文字列。
• Integer（整数）
  • PHP がサポートする任意のサイズのすべての整数（最大 64 ビット）。
• Float（浮動小数点）
  • すべての符号付き浮動小数点値。
• Boolean（ブール）
  • 真と偽
• Null
  • null 値（ただし、キャッシュミスを読み取るときにキャッシュミスと区別できません）。
• 配列（Array）
  • 任意の深さの索引付き、連想型および多次元配列。
• Object（オブジェクト）
  • $o==unserialize(serialize($o)) するようなロスレスシリアル化とデシリアライゼーションをサポートするオブジェクト。 オブジェクトは PHP Serializable インターフェイス、__sleep() または __wakeup() マジックメソッド、または必要に応じて同様の言語機能を利用できます。

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

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

CacheInterface

キャッシュ・インターフェースは、キャッシュ項目の集合に関する最も基本的な操作を定義し、個々のキャッシュ項目の基本的な読み取り、書き込み、および削除を必要とします。

さらに、一度に複数のキャッシュエントリの書き込み、読み出し、または削除などの複数のキャッシュエントリセットを処理する方法もあります。 これは、実行するキャッシュ読み取り/書き込みがたくさんある場合に便利です。また、キャッシュサーバーへの 1 回の呼び出しで操作を実行して、待ち時間を大幅に短縮できます。

<?php

namespace Psr\SimpleCache;

interface CacheInterface
{
    /**
     * キャッシュから値を取得する。
     *
     * @param string $key
     * @param mixed  $default
     *
     * @return mixed
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     */
    public function get($key, $default = null);

    /**
     * キャッシュ内のデータをセットする
     *
     * @param string $key
     * @param mixed $value
     * @param null|int|\DateInterval $ttl
     *
     * @return bool
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     */
    public function set($key, $value, $ttl = null);

    /**
     * キャッシュから項目を削除する。
     *
     * @param string $key
     *
     * @return bool
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     */
    public function delete($key);

    /**
     * キャッシュのキー全体を消去する
     *
     * @return bool
     */
    public function clear();

    /**
     * 固有のキーで複数のキャッシュ項目を取得します。
     *
     * @param iterable $keys
     * @param mixed    $default
     *
     * @return iterable A list of key => value pairs.
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     */
    public function getMultiple($keys, $default = null);

    /**
     * キャッシュ内に key => value のペアのセットします。
     *
     * @param iterable $values
     * @param null|int|\DateInterval $ttl
     *
     * @return bool
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     */
    public function setMultiple($values, $ttl = null);

    /**
     * 複数のキャッシュ項目を削除する
     *
     * @param iterable $keys
     *
     * @return bool
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     */
    public function deleteMultiple($keys);

    /**
     * 項目がキャッシュに存在するかどうかを決定します。
     *
     * @param string $key
     *
     * @return bool
     *
     * @throws \Psr\SimpleCache\InvalidArgumentException
     */
    public function has($key);
}

CacheInterface のインスタンスは、単一のキー名前空間を持つキャッシュアイテムの単一のコレクションに対応し、PSR-6 の「プール」に相当します。 異なる CacheInterface インスタンスは、同じデータストアによってバックアップされていても、論理的に独立していなければなりません。

public function get($key, $default = null);

キャッシュから値を取得します。引数にはキャッシュ内のこのアイテムの一意のキーとキーが存在しない場合に返されるデフォルト値を取ります。戻り値として、キャッシュからの項目の値、またはキャッシュミスの場合の $default 値を返します。

$key 文字列が正当な値でない場合は InvalidArgumentException をスローする必要があります。

public function set($key, $value, $ttl = null);

オプションの有効期限 TTL 時間でキーによって一意に参照されるキャッシュ内のデータをセットします。引数には保存するアイテムのキーと格納する項目を取ります。格納する値はシリアライズ可能である必要があります。第三引数はオプションです。このアイテムの TTL 値ですが、値が送信されず、ドライバが TTL をサポートしている場合、ライブラリはデフォルト値を設定するか、またはドライバがそれを処理するようにします。戻り値として、成功した場合は true, 失敗した場合は false を返します。

$key 文字列が正当な値でない場合は InvalidArgumentException をスローする必要があります。

public function delete($key);

固有のキーでキャッシュから項目を削除します。引数として削除するアイテムの一意のキャッシュキーを取ります。戻り値としてアイテムが正常に削除された場合は true 。 エラーがあった場合は False を返します。

$key 文字列が正当な値でない場合は InvalidArgumentException をスローする必要があります。

public function clear();

キャッシュのキー全体を消去します。戻り値として、成功した場合は true, 失敗した場合は false を返します。

public function getMultiple($keys, $default = null);

固有のキーで複数のキャッシュ項目を取得します。引数には 1 回の操作で取得できるキーのリストと存在しないキーに対して返されるデフォルト値を取ります。戻り値は key/value ペアのリストです。 存在しないか失効しているキャッシュキーは第二引数のデフォルト値を返します。

$keys が配列でも Traversable でもない場合、または $keys のいずれかが正当な値でない場合は InvalidArgumentException をスローする必要があります。

public function setMultiple($values, $ttl = null);

オプションの TTL を使用して、キャッシュ内の key/value のペアのセットを維持します。引数として複数セット操作の key/value ペアのリストとこのアイテムの TTL 値を取ります。第二引数はオプションで、もしここの値がセットされない場合、ドライバが TTL をサポートしているならばライブラリはデフォルト値を設定するか、またはドライバがそれを処理するようにします。戻り値として、成功した場合は true, 失敗した場合は false を返します。

public function deleteMultiple($keys);

1 回の操作で複数のキャッシュ項目を削除します。引数として削除される文字列ベースのキーのリストを取ります。戻り値として、アイテムが正常に削除された場合は true 。 エラーがあった場合は False を返します。

$keys が配列でも Traversable でもない場合、または $keys のいずれかが正当な値でない場合は InvalidArgumentException をスローする必要があります。

public function has($key);

項目がキャッシュに存在するかどうかを返します。引数としてキャッシュアイテムキーを取ります。戻り値は真偽値です。

has() は、キャシュウォーミングタイプの目的にのみ使用され、get/set のライブアプリケーション操作では使用されないようにすることをお勧めします。このメソッドは競合状態になります。 true を返し、直後に別のスクリプトがそれを削除して、アプリの状態を古いものにすることができます。

$key 文字列が正当な値でない場合は InvalidArgumentException をスローする必要があります。

CacheException

実装するライブラリによってスローされるすべてのタイプの例外に使用されるインタフェース。

<?php

namespace Psr\SimpleCache;

interface CacheException
{
}

InvalidArgumentException

無効なキャッシュ引数の例外インタフェース。無効な引数が渡された場合、このインタフェースを実装する例外をスローする必要があります。

<?php

namespace Psr\SimpleCache;

interface InvalidArgumentException extends CacheException
{
}