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

キャッシング

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

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

定義

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

キャッシュ

実装は、特定のキャッシュ項目に対して指定されていない場合、ユーザーがデフォルトの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
{
}