このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン 前のリビジョン 次のリビジョン | 前のリビジョン 最新のリビジョン 両方とも次のリビジョン | ||
psr:psr13 [2020/07/15 09:45] tanaka [3.4 Psr\Link\EvolvableLinkProviderInterface] |
psr:psr13 [2020/07/28 14:06] tanaka [PSR-13: Link definition interfaces] |
||
---|---|---|---|
行 1: | 行 1: | ||
- | > 編集中 | ||
- | |||
====== PSR-13: Link definition interfaces ====== | ====== PSR-13: Link definition interfaces ====== | ||
--- // | --- // | ||
- | 本章は、若干の補足を加筆してはいるものの単に[[https:// | + | 本章は、若干の補足を加筆してはいるものの単に[[https:// |
関連記事 | 関連記事 | ||
行 20: | 行 18: | ||
* PSR-13: Link definition interfaces - リンク定義インターフェース | * PSR-13: Link definition interfaces - リンク定義インターフェース | ||
* [[psr: | * [[psr: | ||
- | * [[psr: | + | * [[psr: |
+ | * [[psr: | ||
+ | * [[psr: | ||
+ | * [[psr: | ||
+ | * [[psr: | ||
----- | ----- | ||
行 28: | 行 30: | ||
--- // 原文より翻訳 [[https:// | --- // 原文より翻訳 [[https:// | ||
- | Hypermedia links are becoming an increasingly important part of the web, in both HTML contexts and various | + | ハイパーメディアリンクは、HTMLコンテキストとさまざまなAPIフォーマットコンテキストの両方で、Webのますます重要な部分になりつつあります。しかしながら、単一の一般的なハイパーメディアフォーマットは無く、フォーマット間のリンクを表す一般的な方法もありません。 |
- | ハイパーメディアリンクは、HTMLコンテキストとさまざまなAPIフォーマットコンテキストの両方で、Webのますます重要な部分になりつつあります。しかしながら、単一の一般的なハイパーメディアフォーマットはなく、フォーマット間のリンクを表す一般的な方法もありません。 | + | この仕様は、PHP開発者に、ハイパーメディアリンクを表す簡単で一般的な方法を提供することを目的としています。それは使用されるシリアル化フォーマットとは独立しています。これにより、システムは応答を、ハイパーメディアリンクで1つまたは複数のワイヤーフォーマットにシリアル化することができます。それは、それらのリンクが何であるかを決定するプロセスとは独立しています。 |
- | + | ||
- | This specification aims to provide PHP developers with a simple, common way of representing a hypermedia link independently of the serialization format that is used. That in turn allows a system to serialize a response with hypermedia links into one or more wire formats independently of the process of deciding what those links should be. | + | |
- | + | ||
- | この仕様は、PHP開発者に、ハイパーメディアリンクを表す簡単で一般的な方法を提供することを目的としています。それは使用されるシリアライゼーションフォーマットとは独立しています。これにより、システムは応答をハイパーメディアリンクで1つまたは複数のワイヤーフォーマットにシリアル化することができます。それは、それらのリンクが何であるかを決定するプロセスとは独立しています。 | + | |
- | + | ||
- | The key words “MUST”, “MUST NOT”, “REQUIRED”, | + | |
このドキュメントのキーワード '' | このドキュメントのキーワード '' | ||
行 60: | 行 56: | ||
===== 1. 仕様 ====== | ===== 1. 仕様 ====== | ||
==== 1.1 基本的なリンク ==== | ==== 1.1 基本的なリンク ==== | ||
- | |||
- | A Hypermedia Link consists of, at minimum: | ||
ハイパーメディアリンクは、少なくとも次のもので構成されます: | ハイパーメディアリンクは、少なくとも次のもので構成されます: | ||
- | |||
- | * A URI representing the target resource being referenced. | ||
- | * A relationship defining how the target resource relates to the source. | ||
* 参照されているターゲットリソースを表すURI | * 参照されているターゲットリソースを表すURI | ||
- | * ターゲットリソースとソースの関係性の定義 | + | * ターゲットリソースとソースの関係の定義 |
- | + | ||
- | Various other attributes of the Link may exist, depending on the format used. As additional attributes are not well-standardized or universal, this specification does not seek to standardize them. | + | |
使用されるフォーマットに応じて、リンクの他のさまざまな属性が存在する場合があります。追加の属性は十分に標準化されていないか普遍的ではないため、この仕様はそれらを標準化することを目指していません。 | 使用されるフォーマットに応じて、リンクの他のさまざまな属性が存在する場合があります。追加の属性は十分に標準化されていないか普遍的ではないため、この仕様はそれらを標準化することを目指していません。 | ||
- | |||
- | For the purposes of this specification, | ||
この仕様の目的の為に、次の定義が適用されます。 | この仕様の目的の為に、次の定義が適用されます。 | ||
- | |||
- | * **Implementing Object** - An object that implements one of the interfaces defined by this specification. | ||
- | * **Serializer** - A library or other system that takes one or more Link objects and produces a serialized representation of it in some defined format. | ||
* **実装オブジェクト** - この仕様で定義されたインターフェースの1つを実装するオブジェクト | * **実装オブジェクト** - この仕様で定義されたインターフェースの1つを実装するオブジェクト | ||
行 88: | 行 72: | ||
==== 1.2 属性 ==== | ==== 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’, | ||
すべてのリンクには、URIおよび関係以外に、追加属性が含まれる場合があります( '' | すべてのリンクには、URIおよび関係以外に、追加属性が含まれる場合があります( '' | ||
- | 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. | + | シリアライザは、シリアル化フォーマットで必要なら、リンクオブジェクトの属性を省略してもよい( '' |
- | + | ||
- | シリアライゼーションフォーマットでは必要に応じて、シリアライザは、リンクオブジェクトの属性を省略してもよい( '' | + | |
- | + | ||
- | 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. | + | |
いくつかの属性(通常は '' | いくつかの属性(通常は '' | ||
- | 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. | + | 属性値がブール値 '' |
- | + | ||
- | 属性値がブール値 '' | + | |
- | + | 属性値がブール値 '' | |
- | 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. | + | |
- | + | ||
- | 属性値がブール値 '' | + | |
\\ | \\ | ||
==== 1.3 関係 ==== | ==== 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のいずれかです。 | リンク関係は文字列として定義されます。それは、パブリックに定義された関係の場合は単純なキーワード、またはプライベートな関係の場合は絶対URIのいずれかです。 | ||
- | |||
- | In case a simple keyword is used, it SHOULD match one from the IANA registry at: | ||
単純なキーワードが使用されている場合、次のIANA( Internet Assigned Number Authority )レジストリのキーワードと一致すべきです( '' | 単純なキーワードが使用されている場合、次のIANA( Internet Assigned Number Authority )レジストリのキーワードと一致すべきです( '' | ||
行 124: | 行 93: | ||
* http:// | * http:// | ||
- | Optionally the microformats.org registry MAY be used, but this may not be valid in every context: | + | オプションで microformats.org レジストリを使用できますが( '' |
- | + | ||
- | オプションでmicroformats.orgレジストリを使用できますが( '' | + | |
* http:// | * http:// | ||
- | |||
- | A relationship that is not defined in one of the above registries or a similar public registry is considered “private”, | ||
上記のレジストリまたは同様のパブリックレジストリのいずれかで定義されていない関係は、「プライベート」と見なされます。つまり、特定のアプリケーションまたはユースケースに固有です。このような関係では、絶対URIを使用する必要があります( '' | 上記のレジストリまたは同様のパブリックレジストリのいずれかで定義されていない関係は、「プライベート」と見なされます。つまり、特定のアプリケーションまたはユースケースに固有です。このような関係では、絶対URIを使用する必要があります( '' | ||
行 138: | 行 103: | ||
==== 1.4 リンクテンプレート ==== | ==== 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:// |
- | + | ||
- | RFC 6570は、URIテンプレートの形式を定義します。つまり、クライアントツールによって提供される値で埋められることが予想されるURIのパターンを定義しています。一部のハイパーメディア形式はテンプレート化されたリンクをサポートしていますが、サポートしていないものもあり、リンクがテンプレートであることを示す特別な方法を持っている場合があります。URIテンプレートをサポートしない形式のシリアライザは、遭遇するテンプレート化されたリンクをすべて無視する必要があります( '' | + | |
\\ | \\ | ||
- | ==== 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, | + | |
さらに、PSR-7 Responseオブジェクトの様ないくつかのリンクプロバイダーオブジェクトは、設計上不変です。つまり、それらへのリンクをインプレースで追加するメソッドには互換性がありません。従って、'' | さらに、PSR-7 Responseオブジェクトの様ないくつかのリンクプロバイダーオブジェクトは、設計上不変です。つまり、それらへのリンクをインプレースで追加するメソッドには互換性がありません。従って、'' | ||
行 156: | 行 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 | + | リンクオブジェクトは、ほとんどの場合、値オブジェクトです。そのため、PSR-7の値オブジェクトと同じ方法でそれらを進化させることは、有用なオプションです。そのため、1回の変更で新しいオブジェクトインスタンスを生成するメソッドを提供する EvolvableLinkInterface が追加されています。同じモデルが PSR-7 で使用されており、PHP の copy-on-write 動作のおかげで、CPUとメモリの効率が向上しています。 |
- | ただし、リンクのテンプレート値はhref値にのみ基づいているので、テンプレート値に対しては発展的な方法はありません。それは、独自に設定することはできませんが( '' | + | ただし、リンクのテンプレート値は href 値にのみ基づいているので、テンプレート値に対しては進化可能な方法はありません。それは、独自に設定することはできませんが( '' |
\\ | \\ | ||
行 172: | 行 127: | ||
The interfaces and classes described are provided as part of the psr/link package. | The interfaces and classes described are provided as part of the psr/link package. | ||
- | 説明されているインターフェースとクラスは、[[https:// | + | 説明されているインターフェースとクラスは、[[https:// |
\\ | \\ | ||
行 186: | 行 141: | ||
/** | /** | ||
- | * A readable link object. | ||
* 読み取り可能なリンクオブジェクト。 | * 読み取り可能なリンクオブジェクト。 | ||
*/ | */ | ||
行 192: | 行 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 | ||
- | | ||
- | * - 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) | * URIテンプレートが返される場合、isTemplated()はTrueを返さなければなりません (MUST) | ||
* | * | ||
行 215: | 行 162: | ||
/** | /** | ||
- | * Returns whether or not this is a templated link. | ||
* これがテンプレートリンクかどうかを返します。 | * これがテンプレートリンクかどうかを返します。 | ||
* | * | ||
* @return bool | * @return bool | ||
- | | ||
| | ||
*/ | */ | ||
行 225: | 行 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[] | * @return string[] | ||
行 237: | 行 179: | ||
/** | /** | ||
- | * Returns a list of attributes that describe the target URI. | ||
* ターゲットURIを説明する属性のリストを返します。 | * ターゲットURIを説明する属性のリストを返します。 | ||
* | * | ||
* @return array | * @return array | ||
- | | ||
- | | ||
- | | ||
| | ||
| | ||
行 261: | 行 199: | ||
/** | /** | ||
- | | + | |
- | * 発展的なリンク値オブジェクト。 | + | |
*/ | */ | ||
interface EvolvableLinkInterface extends LinkInterface | interface EvolvableLinkInterface extends LinkInterface | ||
{ | { | ||
/** | /** | ||
- | * Returns an instance with the specified href. | ||
* 指定されたhrefを持つインスタンスを返します。 | * 指定されたhrefを持つインスタンスを返します。 | ||
* | * | ||
* @param string $href | * @param string $href | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
- | | ||
| | ||
- | | + | |
- | | + | |
- | | + | |
- | | + | |
- | | + | |
* | * | ||
- | * An implementing library SHOULD evaluate a passed object to a string | ||
- | * immediately rather than waiting for it to be returned later. | ||
* 実装ライブラリは、渡されたオブジェクトが後で返されるのを待つのではなく、 | * 実装ライブラリは、渡されたオブジェクトが後で返されるのを待つのではなく、 | ||
* すぐに文字列に評価する必要があります( SHOULD )。 | * すぐに文字列に評価する必要があります( SHOULD )。 | ||
行 295: | 行 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を追加する必要はありません。 | + | |
* | * | ||
* @param string $rel | * @param string $rel | ||
- | | ||
| | ||
* @return static | * @return static | ||
行 311: | 行 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 )。 | * 指定されたrelが既に存在しない場合、このメソッドはエラーなしで正常に戻る必要があります( MUST )。 | ||
* | * | ||
* @param string $rel | * @param string $rel | ||
- | | ||
| | ||
* @return static | * @return static | ||
行 326: | 行 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 | * @param string $attribute | ||
- | | ||
| | ||
* @param string $value | * @param string $value | ||
- | | ||
| | ||
* @return static | * @return static | ||
行 344: | 行 258: | ||
/** | /** | ||
- | * Returns an instance with the specified attribute excluded. | ||
* 指定された属性を除外したインスタンスを返します。 | * 指定された属性を除外したインスタンスを返します。 | ||
* | * | ||
- | * If the specified attribute is not present, this method MUST return | ||
- | * normally without errors. | ||
* 指定された属性が存在しない場合、このメソッドはエラーなしで正常に戻る必要があります( MUST )。 | * 指定された属性が存在しない場合、このメソッドはエラーなしで正常に戻る必要があります( MUST )。 | ||
* | * | ||
* @param string $attribute | * @param string $attribute | ||
- | | ||
| | ||
* @return static | * @return static | ||
行 370: | 行 280: | ||
/** | /** | ||
- | * A link provider object. | ||
* リンクプロバイダーオブジェクト | * リンクプロバイダーオブジェクト | ||
*/ | */ | ||
行 376: | 行 285: | ||
{ | { | ||
/** | /** | ||
- | * Returns an iterable of LinkInterface objects. | ||
* LinkInterfaceオブジェクトのiterableを返します。 | * 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 | * @return LinkInterface[]|\Traversable | ||
行 389: | 行 295: | ||
/** | /** | ||
- | * Returns an iterable of LinkInterface objects that have a specific relationship. | ||
* 特定の関係を持つLinkInterfaceオブジェクトのiterableを返します。 | * 特定の関係を持つ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. | + | |
- | * iterableは、配列または任意のPHP \Traversableオブジェクトです。 その関係を持つリンクがない | + | |
- | | + | |
* | * | ||
* @return LinkInterface[]|\Traversable | * @return LinkInterface[]|\Traversable | ||
行 413: | 行 316: | ||
/** | /** | ||
- | | + | |
- | * 発展的リンクプロバイダー値オブジェクト | + | |
*/ | */ | ||
interface EvolvableLinkProviderInterface extends LinkProviderInterface | 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 | * @param LinkInterface $link | ||
- | | ||
| | ||
* @return static | * @return static | ||
行 436: | 行 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 | * @param LinkInterface $link | ||
- | | ||
| | ||
* @return static | * @return static |