RitoLabo

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

  • 公開:
  • 更新:
  • カテゴリ: PHP PSR
  • タグ: PHP,PSR,PSR-7,PSR-13

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

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

アジェンダ
  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);
}

getLinks()

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);
}

withLink()

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

withoutLink()

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