Skip to content

Latest commit

 

History

History
93 lines (73 loc) · 2.73 KB

psr-8-hug.md

File metadata and controls

93 lines (73 loc) · 2.73 KB
Raw

Mutually Assured Hug

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

1. Overview

This standard establishes a common way for objects to express mutual appreciation and support by hugging. This allows objects to support each other in a constructive fashion, furthering cooperation between different PHP projects.

2. Specification

This specification defines two interfaces, \Psr\Hug\Huggable and \Psr\Hug\GroupHuggable.

Huggable objects

  1. A Huggable object expresses affection and support for another object by invoking its hug() method, passing $this as the first parameter.

  2. An object whose hug() method is invoked MUST hug() the calling object back at least once.

  3. Two objects that are engaged in a hug MAY continue to hug each other back for any number of iterations. However, every huggable object MUST have a termination condition that will prevent an infinite loop. For example, an object MAY be configured to only allow up to 3 mutual hugs, after which it will break the hug chain and return.

  4. An object MAY take additional actions, including modifying state, when hugged. A common example is to increment an internal happiness or satisfaction counter.

GroupHuggable objects

  1. An object may optionally implement GroupHuggable to indicate that it is able to support and affirm multiple objects at once.

3. Interfaces

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 Huggable[] $huggables
   *   An array or iterator of objects implementing the Huggable interface.
   */
  public function groupHug($huggables);
}