このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン 前のリビジョン 次のリビジョン | 前のリビジョン | ||
psr:psr16 [2020/08/04 12:47] tanaka [2.1 CacheInterface] |
psr:psr16 [2020/09/01 11:54] (現在) tanaka [PSR-16: Common Interface for Caching Libraries] |
||
---|---|---|---|
行 1: | 行 1: | ||
- | > 編集中 | ||
- | |||
====== PSR-16: Common Interface for Caching Libraries ====== | ====== PSR-16: Common Interface for Caching Libraries ====== | ||
行 24: | 行 22: | ||
* [[psr: | * [[psr: | ||
* [[psr: | * [[psr: | ||
- | * [[psr: | + | * [[psr: |
----- | ----- | ||
行 31: | 行 29: | ||
--- // 原文より翻訳 [[https:// | --- // 原文より翻訳 [[https:// | ||
- | |||
- | This document describes a simple yet extensible interface for a cache item and a cache driver. | ||
このドキュメントでは、キャッシュアイテムとキャッシュドライバーのシンプルで拡張可能なインターフェースについて説明します。 | このドキュメントでは、キャッシュアイテムとキャッシュドライバーのシンプルで拡張可能なインターフェースについて説明します。 | ||
- | |||
- | The key words “MUST”, “MUST NOT”, “REQUIRED”, | ||
このドキュメントのキーワード '' | このドキュメントのキーワード '' | ||
行 47: | 行 41: | ||
> '' | > '' | ||
- | The final implementations MAY decorate the objects with more functionality than the one proposed but they MUST implement the indicated interfaces/ | + | 最終的な実装は、提案されたものよりも多くの機能でオブジェクトを装飾してもよい( '' |
- | + | ||
- | 最終的な実装は、提案されたものよりも多くの機能でオブジェクトを装飾してもよい( '' | + | |
\\ | \\ | ||
行 55: | 行 47: | ||
===== 1.1 はじめに ===== | ===== 1.1 はじめに ===== | ||
- | Caching is a common way to improve the performance of any project, making caching libraries one of the most common features of many frameworks and libraries. Interoperability at this level means libraries can drop their own caching implementations and easily rely on the one given to them by the framework, or another dedicated cache library. | + | キャッシングは、プロジェクトのパフォーマンスを向上させる一般的な方法であり、キャッシングライブラリは、多くのフレームワークとライブラリの最も一般的な機能の1つになっています。このレベルの相互運用性は、ライブラリが独自のキャッシング実装を止め、フレームワークから提供された実装または別の専用キャッシュライブラリに簡単に依存できることを意味します。 |
- | + | ||
- | キャッシングは、プロジェクトのパフォーマンスを向上させる一般的な方法であり、キャッシングライブラリは、多くのフレームワークとライブラリの最も一般的な機能の1つになっています。このレベルの相互運用性は、ライブラリが独自のキャッシング実装を止め、フレームワークから提供された実装または別の専用キャッシュライブラリに容易に頼れることを意味します。 | + | |
- | + | ||
- | PSR-6 solves this problem already, but in a rather formal and verbose way for what the most simple use cases need. This simpler approach aims to build a standardized streamlined interface for common cases. It is independent of PSR-6 but has been designed to make compatibility with PSR-6 as straightforward as possible. | + | |
- | PSR-6はこの問題をすでに解決していますが、最も簡単なユースケースに必要なものについては、かなり形式的で冗長な方法で行われています。このより簡単なアプローチは、一般的なケースのための標準化された合理化されたインターフェースの構築を目的としています。これは、PSR-6とは独立していますが、PSR-6との互換性をできるだけ簡単にするように設計されています。 | + | PSR-6はこの問題をすでに解決していますが、最も簡単なユースケースに必要なものについては、かなり形式的で冗長な方法で行われています。このより簡単なアプローチは、一般的なケースのために、標準化され、また合理化されたインターフェースの構築を目的としています。これは、PSR-6とは独立していますが、PSR-6との互換性をできるだけ簡単にするように設計されています。 |
\\ | \\ | ||
行 67: | 行 55: | ||
===== 1.2 定義 ===== | ===== 1.2 定義 ===== | ||
- | Definitions for Calling Library, Implementing Library, TTL, Expiration and Key are copied from PSR-6 as the same assumptions are true. | + | ライブラリの呼び出し(Calling Library)、ライブラリの実装(Implementing Library)、TTL、有効期限、キーの定義は、同じ仮定が当てはまるため、PSR-6からコピーしました。 |
- | + | ||
- | ライブラリの呼び出し、ライブラリの実装、TTL、有効期限、キーの定義は、同じ仮定が当てはまるため、PSR-6からコピーされます。 | + | |
* **Calling Library** -- 実際にキャッシュサービスを必要とするライブラリまたはコード。このライブラリは、本規約のインターフェースを実装するキャッシングサービスを利用しますが、その他のキャッシングサービスの実装に関する知識は必要ありません。\\ \\ | * **Calling Library** -- 実際にキャッシュサービスを必要とするライブラリまたはコード。このライブラリは、本規約のインターフェースを実装するキャッシングサービスを利用しますが、その他のキャッシングサービスの実装に関する知識は必要ありません。\\ \\ | ||
- | * Implementing Library - This library is responsible for implementing this standard in order to provide caching services to any Calling Library. <fc # | + | * **Implementing Library** -- Calling Library にキャッシングサービスを提供するために、このライブラリは本規約を実装する責任があります。Implementing Library は、Psr\SimpleCache\CacheInterface インターフェースを実装するクラスを提供する必要があります ( '' |
* **TTL** -- アイテムの残存期間(TTL:Time To Live)は、そのアイテムが保存されてから古くなったと見なされるまでの時間のことです。TTL は通常、秒単位の時間を表す整数、または DateInterval オブジェクトによって定義されます。\\ \\ | * **TTL** -- アイテムの残存期間(TTL:Time To Live)は、そのアイテムが保存されてから古くなったと見なされるまでの時間のことです。TTL は通常、秒単位の時間を表す整数、または DateInterval オブジェクトによって定義されます。\\ \\ | ||
- | * Expiration - The actual time when an item is set to go stale. This is calculated by adding the TTL to the time when an object is stored.\\ \\ **有効期限** -- アイテムが古くなったとに設定された実際の時間。 これは、オブジェクトが格納された時刻にTTLを加算することで計算されます。\\ \\ 300秒の TTL を持つアイテムが 1:30:00 に保存された時、その有効期限は 1:35:00 です。\\ \\ Implementing Library は、要求された有効期限の前にアイテムを期限切れにすることができます ('' | + | * **有効期限** -- アイテムが古くなったとに設定された実際の時間。 これは、オブジェクトが格納された時刻にTTLを加算することで計算されます。\\ \\ 300秒の TTL を持つアイテムが 1:30:00 に保存された時、その有効期限は 1:35:00 です。\\ \\ Implementing Library は、要求された有効期限の前にアイテムを期限切れにすることができます ( '' |
- | * **キー** -- キャッシュされたアイテムを一意に識別する少なくとも1つの文字の文字列。Implementing Library は UTF-8 エンコードで最大 64 文字の長さで任意の順序の文字、'' | + | * **キー** -- キャッシュされたアイテムを一意に識別する少なくとも1つの文字の文字列。Implementing Library は UTF-8 エンコードで最大 64 文字の長さで任意の順序の文字、'' |
- | * Cache - An object that implements the Psr\SimpleCache\CacheInterface interface.\\ \\ **キャッシュ** -- Psr\SimpleCache\CacheInterfaceインターフェースを実装するオブジェクト。\\ \\ | + | * **キャッシュミス** -- キャッシュミスはnullを返すため、nullを格納したか否かは検出できません。これが、PSR-6の仮定から主として逸れている点です。 |
- | * Cache Misses - A cache miss will return null and therefore detecting if one stored null is not possible. This is the main deviation from PSR-6’s assumptions.\\ \\ **キャッシュミス** -- キャッシュミスはnullを返すため、nullを格納したか否かは検出できません。これが、PSR-6の仮定からの主な逸脱です。 | + | |
行 83: | 行 68: | ||
===== 1.3 キャッシュ ===== | ===== 1.3 キャッシュ ===== | ||
- | |||
- | Implementations MAY provide a mechanism for a user to specify a default TTL if one is not specified for a specific cache item. If no user-specified default is provided implementations MUST default to the maximum legal value allowed by the underlying implementation. If the underlying implementation does not support TTL, the user-specified TTL MUST be silently ignored. | ||
特定のキャッシュアイテムにデフォルトのTTLが指定されていない場合に、実装は、ユーザーがデフォルトのTTLを指定するためのメカニズムを提供することがあります( '' | 特定のキャッシュアイテムにデフォルトのTTLが指定されていない場合に、実装は、ユーザーがデフォルトのTTLを指定するためのメカニズムを提供することがあります( '' | ||
行 102: | 行 85: | ||
* **Object** -- '' | * **Object** -- '' | ||
- | Implementing Library に渡されるすべてのデータは、渡されたとおりに返される必要があります ('' | + | Implementing Library に渡されるすべてのデータは、渡されたとおりに返される必要があります ( '' |
- | なんらかの理由で正確に保存された値を返すことができない場合、Implementing library は、破損したデータではなくキャッシュミスで応答する必要があります ('' | + | なんらかの理由で正確に保存された値を返すことができない場合、Implementing library は、破損したデータではなくキャッシュミスで応答する必要があります ( '' |
\\ | \\ | ||
===== 2.1 CacheInterface ===== | ===== 2.1 CacheInterface ===== | ||
- | |||
- | The cache interface defines the most basic operations on a collection of cache-entries, | ||
キャッシュインターフェースは、キャッシュエントリのコレクションに対する最も基本的な操作を定義します。これには、個々のキャッシュアイテムの基本的な読み取り、書き込み、削除が伴います。 | キャッシュインターフェースは、キャッシュエントリのコレクションに対する最も基本的な操作を定義します。これには、個々のキャッシュアイテムの基本的な読み取り、書き込み、削除が伴います。 | ||
- | In addition, it has methods for dealing with multiple sets of cache entries such as writing, reading or deleting multiple cache entries at a time. This is useful when you have lots of cache reads/ | + | さらに、キャッシュエントリの複数のセットを処理するメソッドがあります。これらには、一度に複数のキャッシュエントリの書き込み、読み取り、削除などがあります。これは、実行するキャッシュの読み取り/ |
- | + | ||
- | さらに、キャッシュエントリの複数のセットを処理するメソッドがあります。これらは、一度に複数のキャッシュエントリの書き込み、読み取り、削除があります。これは、実行するキャッシュの読み取り/ | + | |
- | + | ||
- | An instance of CacheInterface corresponds to a single collection of cache items with a single key namespace, and is equivalent to a “Pool” in PSR-6. Different CacheInterface instances MAY be backed by the same datastore, but MUST be logically independent. | + | |
CacheInterfaceのインスタンスは、キャッシュアイテムの単一のコレクションに対応し、それは、単一のキー名前空間を持っています。またそれは、PSR-6の「プール」に相当します。異なるCacheInterfaceのインスタンスは同じデータストアによってサポートされる場合がありますが( '' | CacheInterfaceのインスタンスは、キャッシュアイテムの単一のコレクションに対応し、それは、単一のキー名前空間を持っています。またそれは、PSR-6の「プール」に相当します。異なるCacheInterfaceのインスタンスは同じデータストアによってサポートされる場合がありますが( '' | ||
+ | |||
+ | >'' | ||
+ | >An instance of CacheInterface corresponds to a single collection of cache items with a single key namespace, and is equivalent to a “Pool” in PSR-6. Different CacheInterface instances MAY be backed by the same datastore, but MUST be logically independent. | ||
<code php CacheInterface.php> | <code php CacheInterface.php> | ||
+ | <?php | ||
+ | |||
+ | namespace Psr\SimpleCache; | ||
+ | |||
+ | interface CacheInterface | ||
+ | { | ||
+ | /** | ||
+ | * Fetches a value from the cache. | ||
+ | * キャッシュから値をフェッチします。 | ||
+ | * | ||
+ | * @param string $key The unique key of this item in the cache. | ||
+ | | ||
+ | * @param mixed $default Default value to return if the key does not exist. | ||
+ | | ||
+ | * | ||
+ | * @return mixed The value of the item from the cache, or $default in case of cache miss. | ||
+ | | ||
+ | * | ||
+ | * @throws \Psr\SimpleCache\InvalidArgumentException | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | public function get($key, $default = null); | ||
+ | |||
+ | /** | ||
+ | * Persists data in the cache, uniquely referenced by a key with an optional expiration TTL time. | ||
+ | * オプションの有効期限(TTL)を持つキーによって一意に参照されるデータをキャッシュに永続化します。 | ||
+ | * | ||
+ | * @param string | ||
+ | | ||
+ | * @param mixed | ||
+ | | ||
+ | * @param null|int|\DateInterval $ttl | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | * | ||
+ | * @return bool True on success and false on failure. | ||
+ | | ||
+ | * | ||
+ | * @throws \Psr\SimpleCache\InvalidArgumentException | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | public function set($key, $value, $ttl = null); | ||
+ | |||
+ | /** | ||
+ | * Delete an item from the cache by its unique key. | ||
+ | * ユニークキーによってアイテムをキャッシュから削除します。 | ||
+ | * | ||
+ | * @param string $key The unique cache key of the item to delete. | ||
+ | | ||
+ | * | ||
+ | * @return bool True if the item was successfully removed. False if there was an error. | ||
+ | | ||
+ | * | ||
+ | * @throws \Psr\SimpleCache\InvalidArgumentException | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | public function delete($key); | ||
+ | |||
+ | /** | ||
+ | * Wipes clean the entire cache' | ||
+ | * キャッシュ全体のキーをきれいに消去します。 | ||
+ | * | ||
+ | * @return bool True on success and false on failure. | ||
+ | | ||
+ | */ | ||
+ | public function clear(); | ||
+ | |||
+ | /** | ||
+ | * Obtains multiple cache items by their unique keys. | ||
+ | * ユニークキーで複数のキャッシュアイテムを取得します。 | ||
+ | * | ||
+ | * @param iterable $keys A list of keys that can obtained in a single operation. | ||
+ | | ||
+ | * @param mixed $default Default value to return for keys that do not exist. | ||
+ | | ||
+ | * | ||
+ | * @return iterable A list of key => value pairs. | ||
+ | | ||
+ | | ||
+ | | ||
+ | * | ||
+ | * @throws \Psr\SimpleCache\InvalidArgumentException | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | public function getMultiple($keys, | ||
+ | |||
+ | /** | ||
+ | * Persists a set of key => value pairs in the cache, with an optional TTL. | ||
+ | * オプションのTTLを使用して、「キー => 値」のペアのセットをキャッシュに永続化します。 | ||
+ | * | ||
+ | * @param iterable | ||
+ | | ||
+ | * @param null|int|\DateInterval $ttl Optional. The TTL value of this item. If no value is sent | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | * | ||
+ | * @return bool True on success and false on failure. | ||
+ | | ||
+ | * | ||
+ | * @throws \Psr\SimpleCache\InvalidArgumentException | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | public function setMultiple($values, | ||
+ | |||
+ | /** | ||
+ | * Deletes multiple cache items in a single operation. | ||
+ | * 1回の操作で複数のキャッシュアイテムを削除します。 | ||
+ | * | ||
+ | * @param iterable $keys A list of string-based keys to be deleted. | ||
+ | | ||
+ | * | ||
+ | * @return bool True if the items were successfully removed. False if there was an error. | ||
+ | | ||
+ | * | ||
+ | * @throws \Psr\SimpleCache\InvalidArgumentException | ||
+ | | ||
+ | | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | public function deleteMultiple($keys); | ||
+ | |||
+ | |||
+ | /** | ||
+ | * Determines whether an item is present in the cache. | ||
+ | * アイテムがキャッシュに存在するかどうかを決定します。 | ||
+ | * | ||
+ | * NOTE: It is recommended that has() is only to be used for cache warming type purposes | ||
+ | * and not to be used within your live applications operations for get/set, as this method | ||
+ | * is subject to a race condition where your has() will return true and immediately after, | ||
+ | * another script can remove it, making the state of your app out of date. | ||
+ | * 注:has()は、キャッシュウォーミング的な目的でのみ使用し、get/ | ||
+ | * 操作内では使用しないことをお勧めします。なぜなら、このメソッドは、競合状態の影響を受けるためで、 | ||
+ | * has()が trueを返し、直後に、別のスクリプトがそれを削除して、アプリの状態を古くする可能性が | ||
+ | * あるからです。 | ||
+ | * | ||
+ | * @param string $key The cache item key. | ||
+ | | ||
+ | * | ||
+ | * @return bool | ||
+ | * | ||
+ | * @throws \Psr\SimpleCache\InvalidArgumentException | ||
+ | | ||
+ | | ||
+ | */ | ||
+ | public function has($key); | ||
+ | } | ||
</ | </ | ||
行 128: | 行 272: | ||
===== 2.2 CacheException ===== | ===== 2.2 CacheException ===== | ||
- | >TODO | + | |
+ | <code php CacheException.php> | ||
+ | <?php | ||
+ | |||
+ | namespace Psr\SimpleCache; | ||
+ | |||
+ | /** | ||
+ | * Interface used for all types of exceptions thrown by the implementing library. | ||
+ | * 実装ライブラリによってスローされるすべてのタイプの例外に使用されるインターフェース。 | ||
+ | */ | ||
+ | interface CacheException | ||
+ | { | ||
+ | } | ||
+ | </code> | ||
\\ | \\ | ||
===== 2.3 InvalidArgumentException ===== | ===== 2.3 InvalidArgumentException ===== | ||
- | >TODO | + | |
+ | <code php InvalidArgumentException.php> | ||
+ | <?php | ||
+ | |||
+ | namespace Psr\SimpleCache; | ||
+ | |||
+ | /** | ||
+ | * Exception interface for invalid cache arguments. | ||
+ | * 無効なキャッシュ引数の例外インターフェース。 | ||
+ | * | ||
+ | * When an invalid argument is passed, it must throw an exception which implements | ||
+ | * this interface. | ||
+ | * 無効な引数が渡された場合、このインターフェースを実装する例外をスローする必要があります。 | ||
+ | */ | ||
+ | interface InvalidArgumentException extends CacheException | ||
+ | { | ||
+ | } | ||
+ | </code> | ||
\\ | \\ | ||