差分

このページの2つのバージョン間の差分を表示します。

--- psr:psr16 [2020/08/04 12:44]
tanaka [1.4 データ]
+++ psr:psr16 [2020/09/01 11:54] (現在)
tanaka [PSR-16: Common Interface for Caching Libraries]
@@ 行 1: / 行 1: @@
-> 編集中
 ====== PSR-16: Common Interface for Caching Libraries ======
@@ 行 24: / 行 22: @@
   * [[psr:psr17|PSR-17: HTTP Factories - HTTPファクトリー]]
   * [[psr:psr18|PSR-18: HTTP Client - HTTPクライアント]]
-  * [[psr:psr19|PSR-19: PHPDoc tags - PHPDocタグ]]
+  * [[psr:psr19|PSR-19: PHPDoc tags(Draft) - PHPDocタグ]]
 -----
@@ 行 31: / 行 29: @@
  --- // 原文より翻訳 [[https://www.php-fig.org/psr/psr-16/|PSR-16: Common Interface for Caching Libraries]] 2020-08-04 現在 //
-This document describes a simple yet extensible interface for a cache item and a cache driver.
 このドキュメントでは、キャッシュアイテムとキャッシュドライバーのシンプルで拡張可能なインターフェースについて説明します。
-The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.
 このドキュメントのキーワード ''MUST'' , ''MUST NOT'' , ''REQUIRED'' , ''SHALL'' , ''SHALL NOT'' , ''SHOULD'' , ''SHOULD NOT'' , ''RECOMMENDED'' , ''MAY'' 及び ''OPTIONAL'' は、 [[https://www.ietf.org/rfc/rfc2119.txt|RFC 2119]]で説明されているように解釈して下さい。
@@ 行 47: / 行 41: @@
 > ''MAY'', ''OPTIONAL'' --- オプション
-The final implementations MAY decorate the objects with more functionality than the one proposed but they MUST implement the indicated interfaces/functionality first.
+最終的な実装は、提案されたものよりも多くの機能でオブジェクトを装飾してもよい( ''MAY'' )が、指定されたインターフェース/機能を最初に実装しなければならない( ''MUST'' )。
-最終的な実装は、提案されたものよりも多くの機能でオブジェクトを装飾してもよい( ''MAY'' )が、最初に指定されたインターフェース/機能を実装しなければならない( ''MUST'' )。
 \\
@@ 行 55: / 行 47: @@
 ===== 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はこの問題をすでに解決していますが、最も簡単なユースケースに必要なものについては、かなり形式的で冗長な方法で行われています。このより簡単なアプローチは、一般的なケースのために、標準化され、また合理化されたインターフェースの構築を目的としています。これは、PSR-6とは独立していますが、PSR-6との互換性をできるだけ簡単にするように設計されています。
-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との互換性をできるだけ簡単にするように設計されています。
 \\
@@ 行 67: / 行 55: @@
 ===== 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** -- 実際にキャッシュサービスを必要とするライブラリまたはコード。このライブラリは、本規約のインターフェースを実装するキャッシングサービスを利用しますが、その他のキャッシングサービスの実装に関する知識は必要ありません。\\ \\
-  * Implementing Library - This library is responsible for implementing this standard in order to provide caching services to any Calling Library. <fc #ff0000>The Implementing Library MUST provide a class implementing the Psr\SimpleCache\CacheInterface interface.</fc> Implementing Libraries MUST support at minimum TTL functionality as described below with whole-second granularity.\\ \\ **Implementing Library** -- Calling Library にキャッシングサービスを提供するために、このライブラリは本規約を実装する責任があります。Implementing Library は、Psr\SimpleCache\CacheInterface インターフェースを実装するクラスを提供する必要があります (''MUST'')。Implementing Libraries では、1秒単位で 以下に説明するように、最小限のTTL (Time To Live) 機能をサポートする必要があります (''MUST'')。\\ \\
+  * **Implementing Library** -- Calling Library にキャッシングサービスを提供するために、このライブラリは本規約を実装する責任があります。Implementing Library は、Psr\SimpleCache\CacheInterface インターフェースを実装するクラスを提供する必要があります ( ''MUST'' )。Implementing Libraries では、1秒単位で 以下に説明するように、最小限のTTL (Time To Live) 機能をサポートする必要があります ( ''MUST'' )。\\ \\
   * **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 は、要求された有効期限の前にアイテムを期限切れにすることができます (''MAY'')。ただし、有効期限に達したら、アイテムは期限切れとして扱う必要があります　(''MUST'')。Calling Library はアイテムの保存を要求しますが、有効期限を指定しない場合、または有効期限または TTL を null に指定した場合、Implementing Library は、構成されたデフォルトの期間を使用してもかまいません (''MAY'')。 デフォルトの期間が設定されていない場合、Implementing Library は、それを、アイテムを永久に（または基本となる実装がサポートしている限りの間）キャッシュする要求として、それを解釈する必要があります (''MUST'')。\\ \\ If a negative or zero TTL is provided, the item MUST be deleted from the cache if it exists, as it is expired already. \\ \\ 負またはゼロのTTLが提供されている場合、アイテムは既に期限切れであるため、存在する場合はキャッシュから削除する必要があります( ''MUST'' )。\\ \\
+  * **有効期限** -- アイテムが古くなったとに設定された実際の時間。 これは、オブジェクトが格納された時刻にTTLを加算することで計算されます。\\ \\ 300秒の TTL を持つアイテムが 1:30:00 に保存された時、その有効期限は 1:35:00 です。\\ \\ Implementing Library は、要求された有効期限の前にアイテムを期限切れにすることができます ( ''MAY'' )。ただし、有効期限に達したら、アイテムは期限切れとして扱う必要があります　( ''MUST'' )。Calling Library はアイテムの保存を要求しますが、有効期限を指定しない場合、または有効期限または TTL を null に指定した場合、Implementing Library は、構成されたデフォルトの期間を使用してもかまいません ( ''MAY'' )。 デフォルトの期間が設定されていない場合、Implementing Library は、それを、アイテムを永久に（または基本となる実装がサポートしている限りの間）キャッシュする要求として、それを解釈する必要があります ( ''MUST'' )。\\ \\ 負またはゼロのTTLが提供されている場合、アイテムは既に期限切れであるため、存在する場合はキャッシュから削除する必要があります( ''MUST'' )。\\ \\
-  * **キー** -- キャッシュされたアイテムを一意に識別する少なくとも1つの文字の文字列。Implementing Library は UTF-8 エンコードで最大 64 文字の長さで任意の順序の文字、''A 〜 Z''、''a 〜 z''、''0 〜 9''、アンダースコア(''_'')、およびピリオド(''.'') の文字で構成されるキーをサポートする必要があります (''MUST'')。Implementing Library は、追加の文字とエンコーディング または より長い文字長をサポートする場合がありますが (''MAY'')、少なくともその最小値をサポートしなければなりません(''MUST'')。ライブラリは、必要に応じてキー文字列の独自のエスケープに責任がありますが、変更されていない元のキー文字列を返すことができる必要があります (''MUST'')。 次の文字は、将来の拡張のために予約されており、Implementing Library によってサポートしてはなりません (''MUST NOT'')：''{}()/\@:'' \\ \\
+  * **キー** -- キャッシュされたアイテムを一意に識別する少なくとも1つの文字の文字列。Implementing Library は UTF-8 エンコードで最大 64 文字の長さで任意の順序の文字、''A 〜 Z''、''a 〜 z''、''0 〜 9''、アンダースコア(''_'')、およびピリオド(''.'') の文字で構成されるキーをサポートする必要があります ( ''MUST'' )。Implementing Library は、追加の文字とエンコーディング または より長い文字長をサポートする場合がありますが ( ''MAY'' )、少なくともその最小値をサポートしなければなりません( ''MUST'' )。ライブラリは、必要に応じてキー文字列の独自のエスケープに責任がありますが、変更されていない元のキー文字列を返すことができる必要があります ( ''MUST'' )。 次の文字は、将来の拡張のために予約されており、Implementing Library によってサポートしてはなりません ( ''MUST NOT'' )：''{}()/\@:'' \\ \\
-  * 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 キャッシュ =====
-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を指定するためのメカニズムを提供することがあります( ''MAY'' )。 ユーザー指定のデフォルトが提供されない場合、実装は、基本となる実装で許可されている最大の正当な値にデフォルト設定する必要があります( ''MUST'' )。 基本となる実装がTTLをサポートしない場合、ユーザーが指定したTTLは黙って無視されなければなりません( ''MUST'' )。
@@ 行 102: / 行 85: @@
   * **Object** -- ''$o == unserialize(serialize($o))'' のような、無損失性のシリアライゼーションとデシリアライゼーションをサポートするオブジェクト。オブジェクトは、PHPの Serializable インターフェース、''<nowiki>__</nowiki>sleep()'' または''<nowiki>__</nowiki>wakeup()'' マジックメソッド、または必要に応じて同様の言語機能を活用する場合があります(''MAY'')
-Implementing Library に渡されるすべてのデータは、渡されたとおりに返される必要があります (''MUST'')。それには変数の型も含まれます。つまり、(int)5 が保存された値である場合、(string)5 を返すのはエラーです。ライブラリの実装では、PHPの''serialize()'' / ''unserialize()'' 関数を内部で使用できますが (''MAY'')、必須ではありません。それらとの互換性は、許すことができるオブジェクト値の基準として単に使用されます。
+Implementing Library に渡されるすべてのデータは、渡されたとおりに返される必要があります ( ''MUST'' )。それには変数の型も含まれます。つまり、(int)5 が保存された値である場合、(string)5 を返すのはエラーです。ライブラリの実装では、PHPの''serialize()'' / ''unserialize()'' 関数を内部で使用できますが ( ''MAY'' )、必須ではありません。それらとの互換性は、許すことができるオブジェクト値の基準として単に使用されます。
-なんらかの理由で正確に保存された値を返すことができない場合、Implementing library は、破損したデータではなくキャッシュミスで応答する必要があります (''MUST'')。
+なんらかの理由で正確に保存された値を返すことができない場合、Implementing library は、破損したデータではなくキャッシュミスで応答する必要があります ( ''MUST'' )。
 \\
 ===== 2.1 CacheInterface =====
->TODO
+キャッシュインターフェースは、キャッシュエントリのコレクションに対する最も基本的な操作を定義します。これには、個々のキャッシュアイテムの基本的な読み取り、書き込み、削除が伴います。
+さらに、キャッシュエントリの複数のセットを処理するメソッドがあります。これらには、一度に複数のキャッシュエントリの書き込み、読み取り、削除などがあります。これは、実行するキャッシュの読み取り/書き込みが多い場合に役立ち、キャッシュサーバーへの1回の呼び出しで操作を実行し、待ち時間を大幅に短縮できます。
+CacheInterfaceのインスタンスは、キャッシュアイテムの単一のコレクションに対応し、それは、単一のキー名前空間を持っています。またそれは、PSR-6の「プール」に相当します。異なるCacheInterfaceのインスタンスは同じデータストアによってサポートされる場合がありますが( ''MAY'' )、論理的に独立している必要があります( ''MUST'' )。
+>''上記の原文''
+>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>
+<?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.
+     *               キャッシュからのアイテムの値、またはキャッシュミスの場合は $default。
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     *   MUST be thrown if the $key string is not a legal value.
+     *   $key正当な値でない場合にスローする必要があります(MUST)。
+     */
+    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                $key   The key of the item to store.
+     *                                     保存するアイテムのキー。
+     * @param mixed                 $value The value of the item to store. Must be serializable.
+     *                                     保存するアイテムの値。シリアル化可能でなければなりません。
+     * @param null|int|\DateInterval $ttl   Optional. The TTL value of this item. If no value is sent and
+     *                                     the driver supports TTL then the library may set a default
+     *                                     value for it or let the driver take care of that.
+     *                                     オプション。このアイテムのTTL値。値が送信されず、
+     *                                     ドライバーがTTLをサポートしている場合、ライブラリーは
+     *                                     TTLのデフォルト値を設定するか、ドライバーにそれを
+     *                                     処理させることができます。
+     *
+     * @return bool True on success and false on failure.
+     *              成功した場合は true、失敗した場合は false。
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     *   MUST be thrown if the $key string is not a legal value.
+     *   $keyが正当な値でない場合にスローする必要があります(MUST)。
+     */
+    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.
+     *              アイテムが正常に削除された場合は true。エラーがあった場合は false。
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     *   MUST be thrown if the $key string is not a legal value.
+     *   $keyが正当な値でない場合にスローする必要があります(MUST)。
+     */
+    public function delete($key);
+    /**
+     * Wipes clean the entire cache's keys.
+     * キャッシュ全体のキーをきれいに消去します。
+     *
+     * @return bool True on success and false on failure.
+     *              成功した場合は true、失敗した場合は false。
+     */
+    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.
+     *                          1回の操作で取得できるキーのリスト。
+     * @param mixed    $default Default value to return for keys that do not exist.
+     *                          存在しないキーに対して返すデフォルト値。
+     *
+     * @return iterable A list of key => value pairs.
+     *                  Cache keys that do not exist or are stale will have $default as value.
+     *                  「キー => 値」のペアのリスト。
+     *                  存在しないか古くなっているキャッシュキーは、値として $defaultを持ちます。
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     *   MUST be thrown if $keys is neither an array nor a Traversable,
+     *   or if any of the $keys are not a legal value.
+     *   $keysが配列でも Traversableでもない場合、または $keysのいずれかが正当な値でない場合に
+     *   スローする必要があります(MUST)。
+     */
+    public function getMultiple($keys, $default = null);
+    /**
+     * Persists a set of key => value pairs in the cache, with an optional TTL.
+     * オプションのTTLを使用して、「キー => 値」のペアのセットをキャッシュに永続化します。
+     *
+     * @param iterable               $values A list of key => value pairs for a multiple-set operation.
+     *                                       複数セット操作の「キー => 値」ペアのリスト。
+     * @param null|int|\DateInterval $ttl    Optional. The TTL value of this item. If no value is sent
+     *                                       and the driver supports TTL then the library may set a default
+     *                                       value for it or let the driver take care of that.
+     *                                       オプション。このアイテムのTTL値。値が送信されず、
+     *                                       ドライバーがTTLをサポートしている場合、ライブラリーは
+     *                                       TTLのデフォルト値を設定するか、ドライバーにそれを
+     *                                       処理させることができます。
+     *
+     * @return bool True on success and false on failure.
+     *              成功した場合は true、失敗した場合は false。
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     *   MUST be thrown if $values is neither an array nor a Traversable,
+     *   or if any of the $values are not a legal value.
+     *   $valuesが配列でも Traversableでもない場合、または $valuesのいずれかが正当な値でない場合に
+     *   スローする必要があります(MUST)。
+     */
+    public function setMultiple($values, $ttl = null);
+    /**
+     * 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.
+     *              アイテムが正常に削除された場合は true。エラーがあった場合は false。
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     *   MUST be thrown if $keys is neither an array nor a Traversable,
+     *   or if any of the $keys are not a legal value.
+     *   $keysが配列でも Traversableでもない場合、または $keysのいずれかが正当な値でない場合に
+     *  スローする必要があります(MUST)。
+     */
+    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/setの本番のアプリケーション
+     * 操作内では使用しないことをお勧めします。なぜなら、このメソッドは、競合状態の影響を受けるためで、
+     * has()が trueを返し、直後に、別のスクリプトがそれを削除して、アプリの状態を古くする可能性が
+     * あるからです。
+     *
+     * @param string $key The cache item key.
+     *                    キャッシュアイテムのキー。
+     *
+     * @return bool
+     *
+     * @throws \Psr\SimpleCache\InvalidArgumentException
+     *   MUST be thrown if the $key string is not a legal value.
+     *   $keyが正当な値でない場合にスローする必要があります(MUST)。
+     */
+    public function has($key);
+}
+</code>
 \\
 ===== 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 =====
->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>
 \\

Ground Sunlight

ユーザ用ツール

サイト用ツール

差分

ページ用ツール