差分

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

--- psr:psr13 [2020/07/17 17:47]
y2sunlight [1.1 基本的なリンク]
+++ psr:psr13 [2020/09/01 11:53] (現在)
tanaka [PSR-13: Link definition interfaces]
@@ 行 1: / 行 1: @@
-> 編集中
 ====== PSR-13: Link definition interfaces ======
  --- //[[http://www.y2sunlight.com|y2sunlight]] 2020-06-23//
-本章は、若干の補足を加筆してはいるものの単に[[https://www.php-fig.org/psr/|PSRのサイト]]を翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。
+本章は、若干の補足を加筆してはいるものの単に[[https://www.php-fig.org/psr/|PSRのサイト]]を日本語に翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。
 関連記事
@@ 行 20: / 行 18: @@
   * PSR-13: Link definition interfaces - リンク定義インターフェース
   * [[psr:psr14|PSR-14: Event Dispatcher - イベントディスパッチャー]]
-  * [[psr:psr15|PSR-15: HTTP Handlers - HTTPハンドラー]]
+  * [[psr:psr15|PSR-15: HTTP Server Request Handlers - HTTPサーバーリクエストハンドラー]]
+  * [[psr:psr16|PSR-16: Common Interface for Caching Libraries - キャッシングライブラリのための共通インターフェース]]
+  * [[psr:psr17|PSR-17: HTTP Factories - HTTPファクトリー]]
+  * [[psr:psr18|PSR-18: HTTP Client - HTTPクライアント]]
+  * [[psr:psr19|PSR-19: PHPDoc tags(Draft) - PHPDocタグ]]
 -----
@@ 行 70: / 行 72: @@
 ==== 1.2 属性 ====
-All links MAY include zero or more additional attributes beyond the URI and relationship. There is no formal registry of the values that are allowed here, and validity of values is dependent on context and often on a particular serialization format. Commonly supported values include ‘hreflang’, ‘title’, and ‘type’.
 すべてのリンクには、URIおよび関係以外に、追加属性が含まれる場合があります( ''MAY'' )。ここで許可される値の正式なレジストリはなく、値の有効性はコンテキストに依存し、多くの場合、特定のシリアル化フォーマットに依存します。一般的にサポートされている値には、「hreflang」、「title」、「type」があります。
-Serializers MAY omit attributes on a link object if required to do so by the serialization format. However, serializers SHOULD encode all provided attributes possible in order to allow for user-extension unless prevented by a serialization format’s definition.
+シリアライザは、シリアル化フォーマットで必要なら、リンクオブジェクトの属性を省略してもよい( ''MAY'' )。ただし、シリアライザは、シリアル化フォーマットの定義で妨げられない限り、ユーザー拡張を可能にするために、提供されるすべての属性をエンコードすべきです( ''SHOULD'' )。
-シリアライゼーションフォーマットでは必要に応じて、シリアライザは、リンクオブジェクトの属性を省略してもよい( ''MAY'' )。ただし、シリアライザは、シリアライゼーションフォーマットの定義で妨げられない限り、ユーザー拡張を可能にするために、提供されるすべての属性をエンコードすべきです( ''SHOULD'' )。
-Some attributes (commonly hreflang) may appear more than once in their context. Therefore, an attribute value MAY be an array of values rather than a simple value. Serializers MAY encode that array in whatever format is appropriate for the serialized format (such as a space-separated list, comma-separated list, etc.). If a given attribute is not allowed to have multiple values in a particular context, serializers MUST use the first value provided and ignore all subsequent values.
 いくつかの属性（通常は ''hreflang'' ）は、そのコンテキストで複数回現れることがあります。従って、属性値は単純な値ではなく値の配列である場合があります( ''MAY'' )。シリアライザは、シリアル化されたフォーマット（スペース区切りのリスト、カンマ区切りのリストなど）に適した形式でその配列をエンコードできます( ''MAY'' )。与えられた属性が特定のコンテキストで複数の値を持つことが許可されていない場合、シリアライザは提供された最初の値を使用し、後続のすべての値を無視する必要があります( ''MUST'' )。
-If an attribute value is boolean true, serializers MAY use abbreviated forms if appropriate and supported by a serialization format. For example, HTML permits attributes to have no value when the attribute’s presence has a boolean meaning. This rule applies if and only if the attribute is boolean true, not for any other “truthy” value in PHP such as integer 1.
+属性値がブール値 ''true'' の場合、シリアライザは、適切且つシリアル化フォーマットでサポートされている場合は、省略された形を使用できます( ''MAY'' )。例えば、属性の存在がブール値としての意味を持つ場合、HTMLは属性が値を持つことを許可しません。このルールは、属性がブール値 ''true'' の場合だけに適用され、PHPの整数 1 のような他の「真を表す」値に対しては適用されません。
-属性値がブール値 ''true'' の場合、シリアライザは、適切でありかつシリアル化フォーマットでサポートされている場合は、省略された形を使用できます( ''MAY'' )。例えば、属性の存在がブール値として意味を有する時、HTMLは属性が値を持つことを許可しません。このルールは、属性がブール値 ''true'' の場合だけに適用され、PHPの整数1のような他の「真を表す」値に対しては適用されません。
+属性値がブール値 ''false'' の場合、シリアライザは、結果の意味論的な意味を変更しない限り、属性を完全に省略すべきです( ''SHOULD'' )。このルールは、属性がブール値 ''false'' の場合にのみ適用され、PHPの整数 0 のような他の「偽を表す」値に対しては適用されません。
-If an attribute value is boolean false, serializers SHOULD omit the attribute entirely unless doing so changes the semantic meaning of the result. This rule applies if and only if the attribute is boolean false, not for any other “falsey” value in PHP such as integer 0.
-属性値がブール値 ''false'' の場合、シリアライザは、結果の意味論的な意味を変更しない限り、属性を完全に省略すべきです( ''SHOULD'' )。このルールは、属性がブール値 ''false'' の場合にのみ適用され、PHPの整数0のような他の「偽を表す」値に対しては適用されません。
 \\
 ==== 1.3 関係 ====
-Link relationships are defined as strings, and are either a simple keyword in case of a publicly defined relationship or an absolute URI in the case of a private relationships.
 リンク関係は文字列として定義されます。それは、パブリックに定義された関係の場合は単純なキーワード、またはプライベートな関係の場合は絶対URIのいずれかです。
-In case a simple keyword is used, it SHOULD match one from the IANA registry at:
 単純なキーワードが使用されている場合、次のIANA( Internet Assigned Number Authority )レジストリのキーワードと一致すべきです( ''SHOULD'' )。
@@ 行 106: / 行 93: @@
   * http://www.iana.org/assignments/link-relations/link-relations.xhtml
-Optionally the microformats.org registry MAY be used, but this may not be valid in every context:
+オプションで microformats.org レジストリを使用できますが( ''MAY'' )、これはすべてのコンテキストで有効であるとは限りません。
-オプションでmicroformats.orgレジストリを使用できますが( ''MAY'' )、これはすべてのコンテキストで有効であるとは限りません。
   * http://microformats.org/wiki/existing-rel-values
-A relationship that is not defined in one of the above registries or a similar public registry is considered “private”, that is, specific to a particular application or use case. Such relationships MUST use an absolute URI.
 上記のレジストリまたは同様のパブリックレジストリのいずれかで定義されていない関係は、「プライベート」と見なされます。つまり、特定のアプリケーションまたはユースケースに固有です。このような関係では、絶対URIを使用する必要があります( ''MUST'' )。
@@ 行 120: / 行 103: @@
 ==== 1.4 リンクテンプレート ====
-RFC 6570 defines a format for URI templates, that is, a pattern for a URI that is expected to be filled in with values provided by a client tool. Some hypermedia formats support templated links while others do not, and may have a special way to denote that a link is a template. A Serializer for a format that does not support URI Templates MUST ignore any templated Links it encounters.
+[[https://tools.ietf.org/html/rfc6570|RFC 6570]] は、URIテンプレートの形式を定義します。つまり、クライアントツールによって提供される値で埋められることが予想されるURIのパターンを定義しています。いくつかのハイパーメディア形式はテンプレート化されたリンクをサポートしていますが、サポートしていないものもあり、リンクがテンプレートであることを示す特別な方法を持っている場合があります。URIテンプレートをサポートしない形式のシリアライザは、遭遇するテンプレート化されたリンクをすべて無視する必要があります( ''MUST'' )。
-RFC 6570は、URIテンプレートの形式を定義します。つまり、クライアントツールによって提供される値で埋められることが予想されるURIのパターンを定義しています。一部のハイパーメディア形式はテンプレート化されたリンクをサポートしていますが、サポートしていないものもあり、リンクがテンプレートであることを示す特別な方法を持っている場合があります。URIテンプレートをサポートしない形式のシリアライザは、遭遇するテンプレート化されたリンクをすべて無視する必要があります( ''MUST'' )。
 \\
-==== 1.5 発展的プロバイダー ====
+==== 1.5 進化可能なプロバイダー ====
-In some cases, a Link Provider may need the ability to have additional links added to it. In others, a link provider is necessarily read-only, with links derived at runtime from some other data source. For that reason, modifiable providers are a secondary interface that may optionally be implemented.
+場合によっては、リンクプロバイダーは追加されたリンクを持つ機能が必要になることがあります。他の場合では、リンクプロバイダーは必ず読み取り専用であり、実行時に他のデータソースからリンクが派生します。そのため、変更可能なプロバイダーは、オプションで実装できるセカンダリーインターフェースとなります。
-場合によっては、リンクプロバイダーは追加されたリンクを持つ機能が必要になることがあります。他の場合では、リンクプロバイダーは必ず読み取り専用であり、実行時に他のデータソースからリンクが派生します。そのため、変更可能なプロバイダーは、オプションで実装できるセカンダリインターフェースとなります。
-Additionally, some Link Provider objects, such as PSR-7 Response objects, are by design immutable. That means methods to add links to them in-place would be incompatible. Therefore, the EvolvableLinkProviderInterface’s single method requires that a new object be returned, identical to the original but with an additional Link object included.
 さらに、PSR-7 Responseオブジェクトの様ないくつかのリンクプロバイダーオブジェクトは、設計上不変です。つまり、それらへのリンクをインプレースで追加するメソッドには互換性がありません。従って、''EvolvableLinkProviderInterface'' の単一のメソッドでは、元のオブジェクトと同じですが、追加のリンクオブジェクトが含まれた新しいオブジェクトを返す必要があります。
@@ 行 138: / 行 115: @@
 \\
-==== 1.6 発展的リンクオブジェクト ====
+==== 1.6 進化可能なリンクオブジェクト ====
-Link objects are in most cases value objects. As such, allowing them to evolve in the same fashion as PSR-7 value objects is a useful option. For that reason, an additional EvolvableLinkInterface is included that provides methods to produce new object instances with a single change. The same model is used by PSR-7 and, thanks to PHP’s copy-on-write behavior, is still CPU and memory efficient.
-リンクオブジェクトは、ほとんどの場合値オブジェクトです。そのため、PSR-7値オブジェクトと同じ方法でそれらを発展させることは、有用なオプションです。そのため、1回の変更で新しいオブジェクトインスタンスを生成するメソッドを提供するEvolvableLinkInterfaceが追加されています。同じモデルがPSR-7で使用されており、PHPのcopy-on-write動作のおかげで、CPUとメモリの効率が向上しています。
-There is no evolvable method for templated values, however, as the templated value of a link is based exclusively on the href value. It MUST NOT be set independently, but derived from whether or not the href value is an RFC 6570 link template.
+リンクオブジェクトは、ほとんどの場合、値オブジェクトです。そのため、PSR-7の値オブジェクトと同じ方法でそれらを進化させることは、有用なオプションです。そのため、1回の変更で新しいオブジェクトインスタンスを生成するメソッドを提供する EvolvableLinkInterface が追加されています。同じモデルが PSR-7 で使用されており、PHP の copy-on-write 動作のおかげで、CPUとメモリの効率が向上しています。
-ただし、リンクのテンプレート値はhref値にのみ基づいているので、テンプレート値に対しては発展的な方法はありません。それは、独自に設定することはできませんが( ''MUST NOT'' )、href値がRFC 6570リンクテンプレートであるかどうかに由来しています。
+ただし、リンクのテンプレート値は href 値にのみ基づいているので、テンプレート値に対しては進化可能な方法はありません。それは、独自に設定することはできませんが( ''MUST NOT'' )、href値が RFC 6570 リンクテンプレートであるかどうかに由来しています。
 \\
@@ 行 154: / 行 127: @@
 The interfaces and classes described are provided as part of the psr/link package.
-説明されているインターフェースとクラスは、[[https://packagist.org/packages/psr/link|psr/link]]パッケージの一部として提供されます。
+説明されているインターフェースとクラスは、[[https://packagist.org/packages/psr/link|psr/link]] パッケージの一部として提供されます。
 \\
@@ 行 168: / 行 141: @@
 /**
- * A readable link object.
  * 読み取り可能なリンクオブジェクト。
  */
@@ 行 174: / 行 146: @@
 {
     /**
-     * Returns the target of the link.
      * リンクのターゲットを返します。
      *
-     * The target link must be one of:
-     * - An absolute URI, as defined by RFC 5988.
-     * - A relative URI, as defined by RFC 5988. The base of the relative link
-     *     is assumed to be known based on context by the client.
-     * - A URI template as defined by RFC 6570.
      *
      * ターゲットリンクは次のいずれかである必要があります。
-     * -RFC 5988で定義されている絶対URI。
+     * - RFC 5988で定義されている絶対URI。
-     * -RFC 5988で定義されている相対URI。相対リンクのベースは、クライアントによるコンテキストに
+     * - RFC 5988で定義されている相対URI。相対リンクのベースは、クライアントによるコンテキストに
-     *     基づいて認識されていると想定されています。
+     *   基づいて認識されていると想定されています。
-     * -RFC 6570で定義されているURIテンプレート。
+     * - RFC 6570で定義されているURIテンプレート。
      *
-     * If a URI template is returned, isTemplated() MUST return True.
      * URIテンプレートが返される場合、isTemplated()はTrueを返さなければなりません (MUST)
      *
@@ 行 197: / 行 162: @@
     /**
-     * Returns whether or not this is a templated link.
      * これがテンプレートリンクかどうかを返します。
      *
      * @return bool
-     *   True if this link object is templated, False otherwise.
      *   このリンクオブジェクトがテンプレート化されている場合はTrue、そうでない場合はFalse。
      */
@@ 行 207: / 行 170: @@
     /**
-     * Returns the relationship type(s) of the link.
      * リンクの関係タイプを返します。
      *
-     * This method returns 0 or more relationship types for a link, expressed
+     * このメソッドは、リンクに対し0個以上の関係タイプを文字列の配列として返します。
-     * as an array of strings.
-     * このメソッドは、リンクの0以上の関係タイプを文字列の配列として返します。
      *
      * @return string[]
@@ 行 219: / 行 179: @@
     /**
-     * Returns a list of attributes that describe the target URI.
      * ターゲットURIを説明する属性のリストを返します。
      *
      * @return array
-     *   A key-value list of attributes, where the key is a string and the value
-     *  is either a PHP primitive or an array of PHP strings. If no values are
-     *  found an empty array MUST be returned.
      *  属性のKey-Valueリスト。キーは文字列で、値はPHPプリミティブまたはPHP文字列の配列です。
      *  値が見つからない場合は、空の配列を返す必要があります。
@@ 行 243: / 行 199: @@
 /**
- * An evolvable link value object.
+ * 進化可能なリンク値オブジェクト。
- * 発展的なリンク値オブジェクト。
  */
 interface EvolvableLinkInterface extends LinkInterface
 {
     /**
-     * Returns an instance with the specified href.
      * 指定されたhrefを持つインスタンスを返します。
      *
      * @param string $href
-     *   The href value to include. It must be one of:
-     *     - An absolute URI, as defined by RFC 5988.
-     *     - A relative URI, as defined by RFC 5988. The base of the relative link
-     *       is assumed to be known based on context by the client.
-     *     - A URI template as defined by RFC 6570.
-     *     - An object implementing __toString() that produces one of the above
-     *       values.
      *   含めるhref値。 次のいずれかである必要があります。
-     *     -RFC 5988で定義されている絶対URI。
+     *     - RFC 5988で定義されている絶対URI。
-     *     -RFC 5988で定義されている相対URI。相対リンクのベースは、クライアントによるコンテキストに
+     *     - RFC 5988で定義されている相対URI。相対リンクのベースは、クライアントによるコンテキストに
-     *      基づいて認識されていると想定されています。
+     *       基づいて認識されていると想定されています。
-     *     -RFC 6570で定義されているURIテンプレート。
+     *     - RFC 6570で定義されているURIテンプレート。
-     *     -上記の値の1つを生成する__toString()を実装するオブジェクト。
+     *     - 上記の値の1つを生成する__toString()を実装するオブジェクト。
      *
-     * An implementing library SHOULD evaluate a passed object to a string
-     * immediately rather than waiting for it to be returned later.
      * 実装ライブラリは、渡されたオブジェクトが後で返されるのを待つのではなく、
      * すぐに文字列に評価する必要があります( SHOULD )。
@@ 行 277: / 行 222: @@
     /**
-     * Returns an instance with the specified relationship included.
      * 指定された関係を含むインスタンスを返します。
      *
-     * If the specified rel is already present, this method MUST return
+     * 指定されたrelがすでに存在する場合、このメソッドはエラーなしで正常に戻る必要があります。
-     * normally without errors, but without adding the rel a second time.
+     * 但し、もう一度relを追加する必要はありません。
-     * 指定されたrelがすでに存在する場合、このメソッドはエラーなしで正常に戻る必要がありますが、
-     * もう一度relを追加する必要はありません。
      *
      * @param string $rel
-     *   The relationship value to add.
      *   追加する関係の値。
      * @return static
@@ 行 293: / 行 234: @@
     /**
-     * Returns an instance with the specified relationship excluded.
      * 指定された関係を除外したインスタンスを返します。
      *
-     * If the specified rel is already not present, this method MUST return
-     * normally without errors.
      * 指定されたrelが既に存在しない場合、このメソッドはエラーなしで正常に戻る必要があります( MUST )。
      *
      * @param string $rel
-     *   The relationship value to exclude.
      *   除外する関係値
      * @return static
@@ 行 308: / 行 245: @@
     /**
-     * Returns an instance with the specified attribute added.
      * 指定された属性が追加されたインスタンスを返します。
      *
-     * If the specified attribute is already present, it will be overwritten
-     * with the new value.
      * 指定された属性がすでに存在する場合は、新しい値で上書きされます。
      *
      * @param string $attribute
-     *   The attribute to include.
      *   含める属性
      * @param string $value
-     *   The value of the attribute to set.
      *   設定する属性の値
      * @return static
@@ 行 326: / 行 258: @@
     /**
-     * Returns an instance with the specified attribute excluded.
      * 指定された属性を除外したインスタンスを返します。
      *
-     * If the specified attribute is not present, this method MUST return
-     * normally without errors.
      * 指定された属性が存在しない場合、このメソッドはエラーなしで正常に戻る必要があります( MUST )。
      *
      * @param string $attribute
-     *   The attribute to remove.
      *   削除する属性
      * @return static
@@ 行 352: / 行 280: @@
 /**
- * A link provider object.
  * リンクプロバイダーオブジェクト
  */
@@ 行 358: / 行 285: @@
 {
     /**
-     * Returns an iterable of LinkInterface objects.
      * LinkInterfaceオブジェクトのiterableを返します。
      *
-     * The iterable may be an array or any PHP \Traversable object. If no links
+     * iterableは、配列または任意のPHP \Traversableオブジェクトです。利用可能なリンクがない場合は、
-     * are available, an empty array or \Traversable MUST be returned.
+     * 空の配列 または \Traversableを返す必要があります( MUST )。
-     * iterableは、配列または任意のPHP \Traversableオブジェクトです。 利用可能なリンクがない場合は、
-     * 空の配列または\ Traversableを返す必要があります( MUST )。
      *
      * @return LinkInterface[]|\Traversable
@@ 行 371: / 行 295: @@
     /**
-     * Returns an iterable of LinkInterface objects that have a specific relationship.
      * 特定の関係を持つLinkInterfaceオブジェクトのiterableを返します。
      *
-     * The iterable may be an array or any PHP \Traversable object. If no links
+     * iterableは、配列または任意の PHP \Traversableオブジェクトです。その関係を持つリンクがない場合は、
-     * with that relationship are available, an empty array or \Traversable MUST be returned.
+     * 空の配列 または \Traversable を返す必要があります。( MUST )
-     * iterableは、配列または任意のPHP \Traversableオブジェクトです。 その関係を持つリンクがない
-     * 場合は、空の配列または\Traversableを返す必要があります。
      *
      * @return LinkInterface[]|\Traversable
@@ 行 395: / 行 316: @@
 /**
- * An evolvable link provider value object.
+ * 進化可能なリンクプロバイダー値オブジェクト
- * 発展的リンクプロバイダー値オブジェクト
  */
 interface EvolvableLinkProviderInterface extends LinkProviderInterface
 {
     /**
-     * Returns an instance with the specified link included.
      * 指定されたリンクを含むインスタンスを返します。
      *
-     * If the specified link is already present, this method MUST return normally
-     * without errors. The link is present if $link is === identical to a link
-     * object already in the collection.
      * 指定されたリンクがすでに存在する場合、このメソッドはエラーなしで正常に戻る必要があります。
-     * $linkが===既にコレクションにあるリンクオブジェクトと同一である場合、リンクは存在します。
+     * $linkが既にコレクションにあるリンクオブジェクトと同一( ''==='' )な場合、リンクは存在します。
      *
      * @param LinkInterface $link
-     *   A link object that should be included in this collection.
      *   このコレクションに含める必要のあるリンクオブジェクト。
      * @return static
@@ 行 418: / 行 333: @@
     /**
-     * Returns an instance with the specified link removed.
      * 指定されたリンクが削除されたインスタンスを返します。
      *
-     * If the specified link is not present, this method MUST return normally
-     * without errors. The link is present if $link is === identical to a link
-     * object already in the collection.
      * 指定されたリンクが存在しない場合、このメソッドはエラーなしで正常に戻る必要があります。
-     * $linkが===既にコレクションにあるリンクオブジェクトと同一である場合、リンクは存在します。
+     * $linkが既にコレクションにあるリンクオブジェクトと同一( ''==='' )な場合、リンクは存在します。
      *
      * @param LinkInterface $link
-     *   The link to remove.
      *   削除するリンク。
      * @return static

Ground Sunlight

ユーザ用ツール

サイト用ツール

差分

ページ用ツール