PSR-8 Hug (日本語訳)

3793 ワード
PSR PHP PHP テキストリンク

Mutually Assured Hug (相互高信頼性ハグ)

このドキュメント内の "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", "OPTIONAL" キーワードは RFC 2119 の説明にしたがって解釈されるものとします。

1. 概要

この標準は、オブジェクトが互いの感謝と支持を表明するための、一般的な方法を確立します。 これでオブジェクトは、建設的な方法で互いをサポートすることができ、異なるPHPプロジェクト間の協力を促進します。

2. 仕様

この仕様では2つのインターフェース \Psr\Hug\Huggable と \Psr\Hug\GroupHuggable を定義します。

Huggable オブジェクト

  1. Huggable オブジェクトは、その hug() メソッドを呼び出すさい第一パラメータとして $this を渡すことで、他のオブジェクトへの思いやりと支持を表現します。

  2. hug() メソッドが呼び出されたオブジェクトは、少なくとも1回、呼び出したオブジェクトを hug() し返さなければなりません (MUST)。

  3. ハグするさい2つのオブジェクトは、何度も反復して互いに継続してハグし返すことができます (MAY)。 しかし、すべてのハグ可能オブジェクトは、無限ループを防ぐための終了条件を持っていなければなりません (MUST)。たとえば、最大 3 回までの相互ハグしか許可しないようにオブジェクトを設定すると、その後、ハグの連鎖を破棄して return するといったようにします (MAY)。

  4. ハグされたとき、オブジェクトは、状態の変更などの副次的なアクションをとることができます（MAY）。一般的な例として、内部の幸福感もしくは充足感のカウンターをインクリメントすることが挙げられます。

GroupHuggable オブジェクト

  1. オブジェクトは、複数のオブジェクトを一括で支援/肯定することができることを示す、GroupHuggable を実装することがあります。

3. インターフェース

HuggableInterface

namespace Psr\Hug;

/**
 * Defines a huggable object.
 *
 * A huggable object expresses mutual affection with another huggable object.
 */
interface Huggable
{

    /**
     * Hugs this object.
     *
     * All hugs are mutual. An object that is hugged MUST in turn hug the other
     * object back by calling hug() on the first parameter. All objects MUST
     * implement a mechanism to prevent an infinite loop of hugging.
     *
     * @param Huggable $h
     *   The object that is hugging this object.
     */
    public function hug(Huggable $h);
}

namespace Psr\Hug;

/**
 * Defines a huggable object.
 *
 * A huggable object expresses mutual affection with another huggable object.
 */
interface GroupHuggable extends Huggable
{

  /**
   * Hugs a series of huggable objects.
   *
   * When called, this object MUST invoke the hug() method of every object
   * provided. The order of the collection is not significant, and this object
   * MAY hug each of the objects in any order provided that all are hugged.
   *
   * @param $huggables
   *   An array or iterator of objects implementing the Huggable interface.
   */
  public function groupHug($huggables);
}