このページの2つのバージョン間の差分を表示します。
両方とも前のリビジョン 前のリビジョン 次のリビジョン | 前のリビジョン | ||
psr:psr13 [2020/07/17 18:00] y2sunlight [1.2 属性] |
psr:psr13 [2020/09/01 11:53] (現在) 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: | ||
----- | ----- | ||
行 84: | 行 86: | ||
==== 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 )レジストリのキーワードと一致すべきです( '' | ||
行 95: | 行 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を使用する必要があります( '' | ||
行 109: | 行 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オブジェクトの様ないくつかのリンクプロバイダーオブジェクトは、設計上不変です。つまり、それらへのリンクをインプレースで追加するメソッドには互換性がありません。従って、'' | ||
行 127: | 行 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 値にのみ基づいているので、テンプレート値に対しては進化可能な方法はありません。それは、独自に設定することはできませんが( '' |
\\ | \\ | ||
行 143: | 行 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:// |
\\ | \\ | ||
行 157: | 行 141: | ||
/** | /** | ||
- | * A readable link object. | ||
* 読み取り可能なリンクオブジェクト。 | * 読み取り可能なリンクオブジェクト。 | ||
*/ | */ | ||
行 163: | 行 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) | ||
* | * | ||
行 186: | 行 162: | ||
/** | /** | ||
- | * Returns whether or not this is a templated link. | ||
* これがテンプレートリンクかどうかを返します。 | * これがテンプレートリンクかどうかを返します。 | ||
* | * | ||
* @return bool | * @return bool | ||
- | | ||
| | ||
*/ | */ | ||
行 196: | 行 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[] | ||
行 208: | 行 179: | ||
/** | /** | ||
- | * Returns a list of attributes that describe the target URI. | ||
* ターゲットURIを説明する属性のリストを返します。 | * ターゲットURIを説明する属性のリストを返します。 | ||
* | * | ||
* @return array | * @return array | ||
- | | ||
- | | ||
- | | ||
| | ||
| | ||
行 232: | 行 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 )。 | ||
行 266: | 行 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 | ||
行 282: | 行 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 | ||
行 297: | 行 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 | ||
行 315: | 行 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 | ||
行 341: | 行 280: | ||
/** | /** | ||
- | * A link provider object. | ||
* リンクプロバイダーオブジェクト | * リンクプロバイダーオブジェクト | ||
*/ | */ | ||
行 347: | 行 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 | ||
行 360: | 行 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 | ||
行 384: | 行 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 | ||
行 407: | 行 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 |