1. Home
  2. PHP
  3. PSR
  4. 【PHP】PSR-13 Hypermedia Links（ハイパーメディアリンク）~リンク定義インタフェース~

【PHP】PSR-13 Hypermedia Links（ハイパーメディアリンク）~リンク定義インタフェース~

  • 公開日
  • 更新日
  • カテゴリ：PSR
  • タグ：PHP,PSR,PSR-7,PSR-13
【PHP】PSR-13 Hypermedia Links（ハイパーメディアリンク）~リンク定義インタフェース~

PSR（PHP 標準勧告）

  1. 概要
  2. PSR-1 Basic Coding Standard
  3. PSR-2 Coding Style Guide
  4. PSR-3 Logger Interface
  5. PSR-4 Autoloader
  6. PSR-6 Caching Interface
  7. PSR-7 HTTP Message Interface
  8. PSR-11 Container Interface
  9. PSR-12 Extended Coding Style
  10. PSR-13 Hypermedia Links
  11. PSR-15 HTTP Handlers
  12. PSR-16 Simple Cache
  13. PSR-17 HTTP Factories
  14. PSR-18 HTTP Client

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

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

Contents

  1. 仕様
    1. 基本的なリンク
    2. 属性
    3. リレーション
    4. リンクテンプレート
    5. 変更可能なプロバイダー
    6. 進化可能なリンクオブジェクト
  2. パッケージ
  3. インタフェース
    1. LinkInterface
    2. EvolvableLinkInterface
    3. LinkProviderInterface
    4. EvolvableLinkProviderInterface

仕様

以下に PSR-13 としての仕様を示します。

基本的なリンク

ハイパーメディアリンクは、少なくとも次のものから成ります。

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

使用されるフォーマットに応じて、Link の他のさまざまな属性が存在する可能性があります。 追加の属性があまり標準化されていないか普遍的でないため、この仕様はそれらを標準化しようとはしません。

PSR-13 として、以下を定義します。

  • オブジェクトの実装
    • この仕様で定義されたインタフェースの 1 つを実装するオブジェクト。
  • シリアライザ
    • 1 つまたは複数の Link オブジェクトを使用し、定義済みの形式でシリアライズされた表現を生成するライブラリまたはその他のシステム。

属性

すべてのリンクには、URI 以外の追加の属性が含まれる場合があります。ここで許可されている値の正式なレジストリは存在せず、値の妥当性はコンテキストと特定のシリアライゼーション形式に依存します。一般的にサポートされている値には、「hreflang 」「title 」「type 」があります。

シリアライザは、シリアライゼーション形式でリンクオブジェクトの属性を省略することがあります。ただしシリアライザは、シリアライゼーション形式の定義によって妨げられない限り、ユーザ拡張を可能にするために可能なすべての属性をエンコードする必要があります。

いくつかの属性（一般に hreflang）は、それらの文脈で複数回現れることがあります。したがって、属性値は単純な値ではなく値の配列である可能性があります。シリアライザは、シリアライズされた形式（スペース区切りリスト、コンマ区切りリストなど）に適した形式で配列をエンコードできます。与えられた属性が特定のコンテキストで複数の値を持つことが許されていない場合、シリアライザは最初に指定された値を使用し、その後のすべての値を無視する必要があります。

属性値が bool 値 true の場合、シリアライザは適切な場合には省略形を使用し、シリアライズ形式でサポートされます。たとえば、属性の存在が bool 値の意味を持つ場合、HTML は値を持たない属性を許可します。このルールは、属性が bool 値 true の場合にのみ適用され、整数「1 」などの PHP の他の true 値に対しては適用されません。

属性値が bool 値 false の場合、シリアライザは属性の意味を変更しない限り、属性を完全に省略する必要があります。このルールは、属性が bool 値 false の場合にのみ適用され、整数「0 」などの PHP の他の false 値には適用されません。

リレーション

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

単純なキーワードが使用されている場合は、IANA レジストリ のキーワードと一致する必要があります。

必要に応じて、microformats.org レジストリ を使用することができますが、これは有効ではありません

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

リンクテンプレート

RFC6570 では、URI テンプレートの形式、つまりクライアントツールによって提供される値で埋められると予想される URI のパターンが定義されています。

一部のハイパーメディア形式はテンプレートリンクをサポートしていますが、他のものはサポートしていないため、リンクがテンプレートであることを示す特別な方法があります。 URI テンプレートをサポートしていない形式のシリアライザは、遭遇したテンプレートリンクをすべて無視する必要があります。

変更可能なプロバイダー

場合によっては、リンクプロバイダーに追加のリンクを追加する機能が必要な場合があります。 他のものでは、リンクプロバイダーは必ず読み取り専用であり、実行時に他のデータソースからリンクが導出されます。 そのため、変更可能なプロバイダは、オプションで実装できるセカンダリインターフェイスです。

さらに、PSR-7 レスポンスオブジェクトなどの一部のリンクプロバイダオブジェクトは、設計上不変です。つまり、それらにリンクを追加する方法は、互換性がありません。 したがって、EvolvableLinkProviderInterface の単一のメソッドでは、元のオブジェクトと同じ新しいオブジェクトが返される必要がありますが、追加のリンクオブジェクトが含まれています。

進化可能なリンクオブジェクト

リンクオブジェクトは、ほとんどの場合、値オブジェクトです。 そのため、PSR-7 の値オブジェクトと同じように進化させることは有用な選択肢です。 このため、単一の変更で新しいオブジェクトインスタンスを生成するメソッドを提供する EvolvableLinkInterface が追加されています。 同じモデルが PSR-7 によって使用されています.POS のコピーライト動作のおかげで、依然として CPU とメモリが効率的です。

しかし、リンクのテンプレート化された値は排他的に href 値に基づいているため、テンプレート化のための進化可能なメソッドはありません。 独立して設定する必要はありませんが、href の値が RFC 6570 リンクテンプレートであるかどうかによって決まります。

パッケージ

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

インタフェース

以下に PSR-13 に準拠したインターフェイスを示します。

LinkInterface

読み取り可能なリンクオブジェクト

Psr\Link\LinkInterface
<?php

namespace Psr\Link;

interface LinkInterface
{
    /**
     * リンクのターゲットを返す
     * @return string
     */
    public function getHref();

    /**
     * テンプレート化されたリンクであるかどうかを返す
     * @return bool
     */
    public function isTemplated();

    /**
     * リンクのリレーションシップタイプを返す
     * @return string[]
     */
    public function getRels();

    /**
     * ターゲット URI を記述する属性のリストを返す
     * @return array 属性のキー値リスト
      */
    public function getAttributes();
}

getHref()

public function getHref();

リンクのターゲットを返します。ターゲットリンクは、次のいずれかである必要があります。

  • RFC 5988 で定義されている絶対 URI 。
  • RFC 5988 で定義されている相対 URI 。相対リンクの基底は、クライアントのコンテキストに基づいて既知であると仮定されます。
  • RFC 6570 で定義されている URI テンプレート

URI テンプレートが返された場合、isTemplated() は True を返す必要があります。

isTemplated()

public function isTemplated();

テンプレート化されたリンクであるかどうかを返します。このリンクオブジェクトがテンプレート化されている場合は true, そうでない場合は false を返します。

getRels()

public function getRels();

リンクのリレーションシップタイプを返します。リンクの文字列の配列として表現される 0 以上のリレーションシップタイプを返します。

getAttributes()

public function getAttributes();

ターゲット URI を記述する属性のリストを返します。

戻り値は属性のキー値リストです。キーは文字列で、値は PHP プリミティブまたは PHP 文字列の配列です。値が見つからない場合は空の配列を返します。

EvolvableLinkInterface

リンク値オブジェクト

Psr\Link\EvolvableLinkInterface
<?php

namespace Psr\Link;

interface EvolvableLinkInterface extends LinkInterface
{
    /**
     * 指定された href を持つインスタンスを返す
     * @return static
     */
    public function withHref($href);

    /**
     * 指定されたリレーションが含まれているインスタンスを返す
     * @param string $rel
     * @return static
     */
    public function withRel($rel);

    /**
     * 指定された関係が含まれているインスタンスを返す
     * @param string $rel
     * @return static
     */
    public function withoutRel($rel);

    /**
     * 指定された属性が追加されたインスタンスを返します。
     * @param string $attribute
     * @param string $value
     * @return static
     */
    public function withAttribute($attribute, $value);

    /**
     * 指定した属性が除外されているインスタンスを返す
     * @param string $attribute
     * @return static
     */
    public function withoutAttribute($attribute);
}

withHref()

public function withHref($href);
  • 指定された href を持つインスタンスを返します。
  • 引数には含める href 値を取ります。 次のいずれかである必要があります。
    • RFC 5988 で定義されている絶対 URI 。
    • RFC 5988 で定義されている相対 URI 。相対リンクの基底は、クライアントのコンテキストに基づいて既知であると仮定されます。
    • RFC 6570 で定義されている URI テンプレート。
    • 上記の値のいずれかを生成する__toString() を実装するオブジェクト。
  • 実装するライブラリは、渡されたオブジェクトを後で返されるのを待つのではなく、すぐに文字列に評価する必要があります。

withRel()

public function withRel($rel);
  • 指定されたリレーションが含まれているインスタンスを返します。
  • 引数として追加するリレーションの値を取ります。
  • 指定された rel がすでに存在する場合、このメソッドはエラーなしで正常に戻りますが、rel を 2 回追加する必要はありません。

withoutRel()

public function withoutRel($rel);
  • 指定したリレーションが除外されているインスタンスを返します。
  • 引数として除外するリレーションの値を取ります。
  • 指定された rel がすでに存在しない場合、このメソッドはエラーなしで正常に返されなければなりません。

withAttribute()

public function withAttribute($attribute, $value);
  • 指定された属性が追加されたインスタンスを返します。
  • 引数として設定する属性と属性値を取ります。
  • 指定された属性がすでに存在する場合は、新しい値で上書きされます。

withoutAttribute()

public function withoutAttribute($attribute);
  • 指定した属性が除外されているインスタンスを返します。
  • 引数として削除する属性を取ります。
  • 指定された属性が存在しない場合、このメソッドはエラーなしで正常に返されなければなりません。

LinkProviderInterface

リンクプロバイダオブジェクト

Psr\Link\LinkProviderInterface
<?php

namespace Psr\Link;

interface LinkProviderInterface
{
    /**
     * LinkInterface オブジェクトの反復可能な値を返す。
     * @return LinkInterface[]|\Traversable
     */
    public function getLinks();

    /**
     * 特定の関係を持つ LinkInterface オブジェクトの反復可能なものを返す
     * @return LinkInterface[]|\Traversable
     */
    public function getLinksByRel($rel);
}

public function getLinks();
  • LinkInterface オブジェクトの反復可能な値を返します。
  • iterable は、配列または任意の PHP\Traversable オブジェクトです。 リンクが使用できない場合は、空の配列または\Traversable を返す必要があります。

getLinksByRel()

public function getLinksByRel($rel);
  • 特定のリレーションを持つ LinkInterface オブジェクトの反復可能なものを返します。
  • iterable は、配列または任意の PHP \ Traversable オブジェクトです。 そのリレーションにリンクがない場合は、空の配列または\Traversable を返す必要があります。

EvolvableLinkProviderInterface

リンクプロバイダの値オブジェクト

Psr\Link\EvolvableLinkProviderInterface
<?php

namespace Psr\Link;

interface EvolvableLinkProviderInterface extends LinkProviderInterface
{
    /**
     * 指定されたリンクが含まれているインスタンスを返す
     * @param LinkInterface $link
     * @return static
     */
    public function withLink(LinkInterface $link);

    /**
     * 指定されたリンクが削除されたインスタンスを返す
     * @param LinkInterface $link
     * @return static
     */
    public function withoutLink(LinkInterface $link);
}

public function withLink(LinkInterface $link);
  • 指定されたリンクが含まれているインスタンスを返します。
  • 引数としてこのコレクションに含めるリンクオブジェクトを取ります。
  • 指定されたリンクがすでに存在する場合、このメソッドはエラーなしで正常に返されなければなりません。 $link が既にコレクションにあるリンクオブジェクトと同じであればリンクが存在します。
public function withoutLink(LinkInterface $link);
  • 指定されたリンクが削除されたインスタンスを返します。
  • 引数として削除するリンクを取ります。
  • 指定されたリンクが存在しない場合、このメソッドはエラーなしで正常に返されなければなりません。 $link が既にコレクションにあるリンクオブジェクトと同じであればリンクが存在します。

Author

rito

  • Backend Engineer
  • Tokyo, Japan
  • PHP 5 技術者認定上級試験　認定者
  • 統計検定 3 級