— y2sunlight 2020-06-23

本章は、若干の補足を加筆してはいるものの単にPSRのサイトを翻訳したものに過ぎません。英語が堪能な方は原文をご参照下さい。翻訳に当たっては、基本的に機械翻訳を使い、理解できない部分は独断で意訳しております。拙い訳では御座いますが恥を忍んで投稿しておりますので、ご指摘など御座いましたらコメントを頂ければ幸いです。

関連記事

• PSR - PHP標準勧告
• PSR-1: Basic Coding Standard - 基本コーディング規約
• PSR-3: Logger Interface - ロガーインターフェイス
• PSR-4: Autoloading Standard - オートローディング規約
• PSR-5: PHPDoc Standard(Draft) - PHPDoc規約
• PSR-6: Caching Interface - キャッシングインターフェイス
• PSR-7: HTTP Message Interface - HTTPメッセージインターフェイス
• PSR-11: Container Interface - コンテナインターフェイス
• PSR-12: Extended Coding Style - 拡張コーディングスタイル
• PSR-13: Link definition interfaces - リンク定義インターフェース
• PSR-14: Event Dispatcher - イベントディスパッチャー
• PSR-15: HTTP Handlers - HTTPハンドラー

— 原文より翻訳 PSR-13: Link definition interfaces 2020-07-14 現在

ハイパーメディアリンクは、HTMLコンテキストとさまざまなAPIフォーマットコンテキストの両方で、Webのますます重要な部分になりつつあります。しかしながら、単一の一般的なハイパーメディアフォーマットは無く、フォーマット間のリンクを表す一般的な方法もありません。

この仕様は、PHP開発者に、ハイパーメディアリンクを表す簡単で一般的な方法を提供することを目的としています。それは使用されるシリアル化フォーマットとは独立しています。これにより、システムは応答を、ハイパーメディアリンクで1つまたは複数のワイヤーフォーマットにシリアル化することができます。それは、それらのリンクが何であるかを決定するプロセスとは独立しています。

このドキュメントのキーワード MUST , MUST NOT , REQUIRED , SHALL , SHALL NOT , SHOULD , SHOULD NOT , RECOMMENDED , MAY 及び OPTIONAL は、 RFC 2119で説明されているように解釈して下さい。

RFC 2119の説明
MUST, REQUIRED, SHALL — 絶対必要
MUST NOT, SHALL NOT — 絶対禁止
SHOULD, RECOMMENDED — 推奨（但し、無視できる特定の正当な理由が存在するかもしれない）
SHOULD NOT — 推奨できない（但し、許可できる特定の正当な理由が存在するかもしれない）
MAY, OPTIONAL — オプション

• RFC 2119　・・・　Key words for use in RFCs to Indicate Requirement Levels
• RFC 4287　・・・　The Atom Syndication Format
• RFC 5988　・・・　Web Linking
• RFC 6570　・・・　URI Template
• IANA Link Relations Registry　・・・　Link Relations
• Microformats Relations List　・・・　HTML5 link type extensions

ハイパーメディアリンクは、少なくとも次のもので構成されます：

• 参照されているターゲットリソースを表すURI
• ターゲットリソースとソースの関係の定義

使用されるフォーマットに応じて、リンクの他のさまざまな属性が存在する場合があります。追加の属性は十分に標準化されていないか普遍的ではないため、この仕様はそれらを標準化することを目指していません。

この仕様の目的の為に、次の定義が適用されます。

• 実装オブジェクト - この仕様で定義されたインターフェースの1つを実装するオブジェクト
• シリアライザ - 1つまたは複数のリンクオブジェクトを受け取り、それを何らかの定義された形式でシリアル化した表現を生成するライブラリまたは他のシステム

すべてのリンクには、URIおよび関係以外に、追加属性が含まれる場合があります( MAY )。ここで許可される値の正式なレジストリはなく、値の有効性はコンテキストに依存し、多くの場合、特定のシリアル化フォーマットに依存します。一般的にサポートされている値には、「hreflang」、「title」、「type」があります。

シリアライザは、シリアル化フォーマットで必要なら、リンクオブジェクトの属性を省略してもよい( MAY )。ただし、シリアライザは、シリアル化フォーマットの定義で妨げられない限り、ユーザー拡張を可能にするために、提供されるすべての属性をエンコードすべきです( SHOULD )。

いくつかの属性（通常は hreflang ）は、そのコンテキストで複数回現れることがあります。従って、属性値は単純な値ではなく値の配列である場合があります( MAY )。シリアライザは、シリアル化されたフォーマット（スペース区切りのリスト、カンマ区切りのリストなど）に適した形式でその配列をエンコードできます( MAY )。与えられた属性が特定のコンテキストで複数の値を持つことが許可されていない場合、シリアライザは提供された最初の値を使用し、後続のすべての値を無視する必要があります( MUST )。

属性値がブール値 true の場合、シリアライザは、適切且つシリアル化フォーマットでサポートされている場合は、省略された形を使用できます( MAY )。例えば、属性の存在がブール値としての意味を持つ場合、HTMLは属性が値を持つことを許可しません。このルールは、属性がブール値 true の場合だけに適用され、PHPの整数 1 のような他の「真を表す」値に対しては適用されません。   属性値がブール値 false の場合、シリアライザは、結果の意味論的な意味を変更しない限り、属性を完全に省略すべきです( SHOULD )。このルールは、属性がブール値 false の場合にのみ適用され、PHPの整数 0 のような他の「偽を表す」値に対しては適用されません。

リンク関係は文字列として定義されます。それは、パブリックに定義された関係の場合は単純なキーワード、またはプライベートな関係の場合は絶対URIのいずれかです。

単純なキーワードが使用されている場合、次のIANA( Internet Assigned Number Authority )レジストリのキーワードと一致すべきです( SHOULD )。

• http://www.iana.org/assignments/link-relations/link-relations.xhtml

オプションで microformats.org レジストリを使用できますが( MAY )、これはすべてのコンテキストで有効であるとは限りません。

• http://microformats.org/wiki/existing-rel-values

上記のレジストリまたは同様のパブリックレジストリのいずれかで定義されていない関係は、「プライベート」と見なされます。つまり、特定のアプリケーションまたはユースケースに固有です。このような関係では、絶対URIを使用する必要があります( MUST )。

RFC 6570 は、URIテンプレートの形式を定義します。つまり、クライアントツールによって提供される値で埋められることが予想されるURIのパターンを定義しています。いくつかのハイパーメディア形式はテンプレート化されたリンクをサポートしていますが、サポートしていないものもあり、リンクがテンプレートであることを示す特別な方法を持っている場合があります。URIテンプレートをサポートしない形式のシリアライザは、遭遇するテンプレート化されたリンクをすべて無視する必要があります( MUST )。

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 の単一のメソッドでは、元のオブジェクトと同じですが、追加のリンクオブジェクトが含まれた新しいオブジェクトを返す必要があります。

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.

ただし、リンクのテンプレート値はhref値にのみ基づいているので、テンプレート値に対しては発展的な方法はありません。それは、独自に設定することはできませんが( MUST NOT )、href値がRFC 6570リンクテンプレートであるかどうかに由来しています。

The interfaces and classes described are provided as part of the psr/link package.

説明されているインターフェースとクラスは、psr/linkパッケージの一部として提供されます。

LinkInterface.php

<?php
 
namespace Psr\Link;
 
/**
 * A readable link object.
 * 読み取り可能なリンクオブジェクト。
 */
interface LinkInterface
{
    /**
     * 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 6570で定義されているURIテンプレート。
     *
     * If a URI template is returned, isTemplated() MUST return True.
     * URIテンプレートが返される場合、isTemplated()はTrueを返さなければなりません (MUST)
     *
     * @return string
     */
    public function getHref();
 
    /**
     * Returns whether or not this is a templated link.
     * これがテンプレートリンクかどうかを返します。
     *
     * @return bool
     *   True if this link object is templated, False otherwise.
     *   このリンクオブジェクトがテンプレート化されている場合はTrue、そうでない場合はFalse。
     */
    public function isTemplated();
 
    /**
     * Returns the relationship type(s) of the link.
     * リンクの関係タイプを返します。
     *
     * This method returns 0 or more relationship types for a link, expressed
     * as an array of strings.
     * このメソッドは、リンクの0以上の関係タイプを文字列の配列として返します。
     *
     * @return string[]
     */
    public function getRels();
 
    /**
     * 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文字列の配列です。 
     *  値が見つからない場合は、空の配列を返す必要があります。
     */
    public function getAttributes();
}

EvolvableLinkInterface.php

<?php
 
namespace Psr\Link;
 
/**
 * 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 6570で定義されているURIテンプレート。
     *     -上記の値の1つを生成する__toString()を実装するオブジェクト。
     *
     * An implementing library SHOULD evaluate a passed object to a string
     * immediately rather than waiting for it to be returned later.
     * 実装ライブラリは、渡されたオブジェクトが後で返されるのを待つのではなく、
     * すぐに文字列に評価する必要があります( SHOULD )。
     *
     * @return static
     */
    public function withHref($href);
 
    /**
     * Returns an instance with the specified relationship included.
     * 指定された関係を含むインスタンスを返します。
     *
     * If the specified rel is already present, this method MUST return
     * normally without errors, but without adding the rel a second time.
     * 指定されたrelがすでに存在する場合、このメソッドはエラーなしで正常に戻る必要がありますが、
     * もう一度relを追加する必要はありません。
     *
     * @param string $rel
     *   The relationship value to add.
     *   追加する関係の値。
     * @return static
     */
    public function withRel($rel);
 
    /**
     * 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
     */
    public function withoutRel($rel);
 
    /**
     * 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
     */
    public function withAttribute($attribute, $value);
 
    /**
     * 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
     */
    public function withoutAttribute($attribute);
}

LinkProviderInterface.php

<?php
 
namespace Psr\Link;
 
/**
 * A link provider object.
 * リンクプロバイダーオブジェクト
 */
interface LinkProviderInterface
{
    /**
     * Returns an iterable of LinkInterface objects.
     * LinkInterfaceオブジェクトのiterableを返します。
     *
     * The iterable may be an array or any PHP \Traversable object. If no links
     * are available, an empty array or \Traversable MUST be returned.
     * iterableは、配列または任意のPHP \Traversableオブジェクトです。 利用可能なリンクがない場合は、
     * 空の配列または\ Traversableを返す必要があります( MUST )。
     *
     * @return LinkInterface[]|\Traversable
     */
    public function getLinks();
 
    /**
     * 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
     * with that relationship are available, an empty array or \Traversable MUST be returned.
     * iterableは、配列または任意のPHP \Traversableオブジェクトです。 その関係を持つリンクがない
     * 場合は、空の配列または\Traversableを返す必要があります。
     *
     * @return LinkInterface[]|\Traversable
     */
    public function getLinksByRel($rel);
}

EvolvableLinkProviderInterface.php

<?php
 
namespace Psr\Link;
 
/**
 * 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が===既にコレクションにあるリンクオブジェクトと同一である場合、リンクは存在します。
     *
     * @param LinkInterface $link
     *   A link object that should be included in this collection.
     *   このコレクションに含める必要のあるリンクオブジェクト。
     * @return static
     */
    public function withLink(LinkInterface $link);
 
    /**
     * 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が===既にコレクションにあるリンクオブジェクトと同一である場合、リンクは存在します。
     *
     * @param LinkInterface $link
     *   The link to remove.
     *   削除するリンク。
     * @return static
     */
    public function withoutLink(LinkInterface $link);
}