add an InverseFunctionalIdentifier class

CHANGELOG.md

@@ -4,6 +4,9 @@ CHANGELOG
 0.2.0
 -----
 
+* added a dedicated class to refer to inverse functional identifiers, refer to
+  the upgrade file for more detailed information
+
 * marked the `Statement` class as final
 
 0.1.0

UPGRADE.md

@@ -4,5 +4,70 @@ UPGRADE
 Upgrading from 0.1 to 0.2
 -------------------------
 
+* the getter methods to retrieve the inverse functional identifier properties
+  `mbox`, `mboxsha1sum`, `openid`, and `account` have been removed from the
+  `Actor` class
+
+* the `getInverseFunctionalIdentifier()` method in the `Actor` class no longer
+  returns a string, but returns an `InverseFunctionalIdentifier` instance
+  instead
+
+* A new class `InverseFunctionalIdentifier` was introduced to reflect the
+  inverse functional identifier of an actor. It reflects the fact that an IRI
+  must only contain exactly one property of `mbox`, `mboxsha1sum`, `openid`,
+  and `account` by providing four factory methods to obtain an IRI instance:
+
+  * `withMbox()`
+
+  * `withMboxSha1Sum()`
+
+  * `withOpenId()`
+
+  * `withAccount()`
+
+  You now need to pass an `InverseFunctionalIdentifier` when creating an actor
+  or group.
+
+  Before:
+
+  ```php
+  use Xabbuh\XApi\Model\Agent;
+  use Xabbuh\XApi\Model\Group;
+
+  $agent = new Agent(
+      'mailto:christian@example.com',
+      null,
+      null,
+      null,
+      'Christian'
+  );
+  $group = new Group(
+      null,
+      null,
+      null,
+      new Account('GroupAccount', 'http://example.com/homePage'),
+      'Example Group'
+  );
+  ```
+
+  After:
+
+  ```php
+  use Xabbuh\XApi\Model\Agent;
+  use Xabbuh\XApi\Model\Group;
+  use Xabbuh\XApi\Model\InverseFunctionalIdentifier;
+
+  $agent = new Agent(
+      InverseFunctionalIdentifier::withMbox('mailto:christian@example.com'),
+      'Christian'
+  );
+  $group = new Group(
+      InverseFunctionalIdentifier::withAccount(
+          new Account('GroupAccount', 'http://example.com/homePage')
+      ),
+      'Example Group'
+  );
+  ```
+
 * The `Statement` class is now marked as final. This means that you can no
-  longer extend this.
+  longer extend it.

src/Actor.php

@@ -19,75 +19,36 @@
 abstract class Actor
 {
     /**
-     * Name of the {@link Agent} or {@link Group}
-     * @var string
-     */
-    private $name;
-
-    /**
-     * A mailto IRI
-     * @var string
-     */
-    private $mbox;
-
-    /**
-     * The SHA1 hash of a mailto IRI
-     * @var string
+     * The actor's {@link InverseFunctionalIdentifier inverse functional identifier}
+     *
+     * @var InverseFunctionalIdentifier
      */
-    private $mboxSha1Sum;
+    private $iri;
 
     /**
-     * An openID uniquely identifying an Agent
+     * Name of the {@link Agent} or {@link Group}
      * @var string
      */
-    private $openId;
-
-    /**
-     * A user account on an existing system
-     * @var Account
-     */
-    private $account;
+    private $name;
 
     /**
-     * @param string  $mbox
-     * @param string  $mboxSha1Sum
-     * @param string  $openId
-     * @param Account $account
-     * @param string  $name
+     * @param InverseFunctionalIdentifier $iri
+     * @param string                      $name
      */
-    public function __construct($mbox = null, $mboxSha1Sum = null, $openId = null, Account $account = null, $name = null)
+    public function __construct(InverseFunctionalIdentifier $iri, $name = null)
     {
+        $this->iri = $iri;
         $this->name = $name;
-        $this->mbox = $mbox;
-        $this->mboxSha1Sum = $mboxSha1Sum;
-        $this->openId = $openId;
-        $this->account = $account;
     }
 
     /**
-     * Returns the Actor's inverse functional identifier.
+     * Returns the Actor's {@link InverseFunctionalIdentifier inverse functional identifier}.
      *
-     * @return string The inverse functional identifier
+     * @return InverseFunctionalIdentifier The inverse functional identifier
      */
     public function getInverseFunctionalIdentifier()
     {
-        if (null !== $this->mbox) {
-            return $this->mbox;
-        }
-
-        if (null !== $this->mboxSha1Sum) {
-            return $this->mboxSha1Sum;
-        }
-
-        if (null !== $this->openId) {
-            return $this->openId;
-        }
-
-        if (null !== $this->account) {
-            return $this->account;
-        }
-
-        return null;
+        return $this->iri;
     }
 
     /**
@@ -100,46 +61,6 @@ public function getName()
         return $this->name;
     }
 
-    /**
-     * Returns the mailto IRI.
-     *
-     * @return string The mailto IRI
-     */
-    public function getMbox()
-    {
-        return $this->mbox;
-    }
-
-    /**
-     * Returns the SHA1 hash of a mailto IRI.
-     *
-     * @return string The SHA1 hash of a mailto IRI
-     */
-    public function getMboxSha1Sum()
-    {
-        return $this->mboxSha1Sum;
-    }
-
-    /**
-     * Returns the openID.
-     *
-     * @return string The openID
-     */
-    public function getOpenId()
-    {
-        return $this->openId;
-    }
-
-    /**
-     * Returns the user account of an existing system.
-     *
-     * @return Account The user account of an existing system
-     */
-    public function getAccount()
-    {
-        return $this->account;
-    }
-
     /**
      * Checks if another actor is equal.
      *
@@ -155,27 +76,7 @@ public function equals(Actor $actor)
             return false;
         }
 
-        if ($this->mbox !== $actor->mbox) {
-            return false;
-        }
-
-        if ($this->mboxSha1Sum !== $actor->mboxSha1Sum) {
-            return false;
-        }
-
-        if ($this->openId !== $actor->openId) {
-            return false;
-        }
-
-        if (null === $this->account && null !== $actor->account) {
-            return false;
-        }
-
-        if (null !== $this->account && null === $actor->account) {
-            return false;
-        }
-
-        if (null !== $this->account && !$this->account->equals($actor->account)) {
+        if (!$this->iri->equals($actor->getInverseFunctionalIdentifier())) {
             return false;
         }
 

src/Group.php

@@ -24,16 +24,13 @@ final class Group extends Actor
     private $members = array();
 
     /**
-     * @param string  $mbox
-     * @param string  $mboxSha1Sum
-     * @param string  $openId
-     * @param Account $account
-     * @param string  $name
-     * @param Agent[] $members
+     * @param InverseFunctionalIdentifier $iri
+     * @param string                      $name
+     * @param Agent[]                     $members
      */
-    public function __construct($mbox = null, $mboxSha1Sum = null, $openId = null, Account $account = null, $name = null, array $members = array())
+    public function __construct(InverseFunctionalIdentifier $iri, $name = null, array $members = array())
     {
-        parent::__construct($mbox, $mboxSha1Sum, $openId, $account, $name);
+        parent::__construct($iri, $name);
 
         $this->members = $members;
     }