Add accessor methods.

gwa · Aug 28, 2018 · 1ae2a6b · 1ae2a6b
1 parent f0412a1
commit 1ae2a6b
Show file tree

Hide file tree

Showing 4 changed files with 93 additions and 17 deletions.
diff --git a/README.md b/README.md
@@ -26,10 +26,10 @@ $contact = new Contact();
 
 // Set the name.
 // Arguments: last, first, middle
-$contact->setName('Doe', 'John');
-
-// Prefix and suffix can also be set
-$contact->name()->setNamePrefix('Dr.');
+$contact->setName('Doe', 'John')
+    // Prefix and suffix can also be set
+    ->setNamePrefix('Dr.')
+    ->setNameSuffix('MD');
 
 // Add a note.
 $contact->setNote('Lorem ipsum');
@@ -52,6 +52,36 @@ $contact->addAddress('1600 Amphitheatre Parkway', 'work', true)
     // Arguments: County, Country code (opt.) https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
     ->setCountry('U.S.A.', 'US');
 
+// Access existing elements using 0-based index:
+$email1 = $contact->email(0);
+$email2 = $contact->email(1);
+$phonenumber1 = $contact->phoneNumber(0);
+$address1 = $contact->address(0);
+
 // Render as XML.
 $xmlstring = $contact->render();
 ```
+
+The following XML is rendered:
+
+```xml
+<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gd="http://schemas.google.com/g/2005">
+  <category scheme="http://schemas.google.com/g/2005#kind" term="http://schemas.google.com/contact/2008#contact"/>
+  <gd:name>
+    <gd:givenName>John</gd:givenName>
+    <gd:familyName>Doe</gd:familyName>
+    <gd:namePrefix>Dr.</gd:namePrefix>
+    <gd:nameSuffix>MD</gd:nameSuffix>
+  </gd:name>
+  <content>Lorem ipsum</content>
+  <gd:email rel="http://schemas.google.com/g/2005#home" primary="true" address="doe@example.org"/>
+  <gd:email rel="http://schemas.google.com/g/2005#work" address="doe@example.com"/>
+  <gd:phoneNumber rel="http://schemas.google.com/g/2005#home" primary="true">012 3456 789</gd:phoneNumber>
+  <gd:structuredPostalAddress rel="http://schemas.google.com/g/2005#work" primary="true">
+    <gd:street>1600 Amphitheatre Parkway</gd:street>
+    <gd:city>Mountain View</gd:city>
+    <gd:region>California</gd:region>
+    <gd:country code="US">U.S.A.</gd:country>
+  </gd:structuredPostalAddress>
+</entry>
+```
diff --git a/src/Contact.php b/src/Contact.php
@@ -46,7 +46,7 @@ class Contact
      * @param string $givenName
      * @param string $additionalName
      *
-     * @return self
+     * @return Name
      */
     public function setName($familyName, $givenName, $additionalName = '')
     {
@@ -58,7 +58,7 @@ public function setName($familyName, $givenName, $additionalName = '')
             $this->name()->setAdditionalName($additionalName);
         }
 
-        return $this;
+        return $this->name();
     }
 
     /**
@@ -95,7 +95,7 @@ public function setNote($note)
      * @param string $type
      * @param boolean $primary
      *
-     * @return self
+     * @return Email
      */
     public function addEmail($address, $type = '', $primary = false)
     {
@@ -104,15 +104,26 @@ public function addEmail($address, $type = '', $primary = false)
         $this->handleTypedPrimary($email, $type, $primary);
         $this->emails[] = $email;
 
-        return $this;
+        return $email;
     }
 
     /**
-     * @param string $address
+     * @param int $index
+     * @return Email|NULL
+     */
+    public function email($index)
+    {
+        return array_key_exists($index, $this->emails) ?
+            $this->emails[$index] :
+            null;
+    }
+
+    /**
+     * @param string $number
      * @param string $type
      * @param boolean $primary
      *
-     * @return self
+     * @return PhoneNumber
      */
     public function addPhoneNumber($number, $type = '', $primary = false)
     {
@@ -121,15 +132,26 @@ public function addPhoneNumber($number, $type = '', $primary = false)
         $this->handleTypedPrimary($phonenumber, $type, $primary);
         $this->phoneNumbers[] = $phonenumber;
 
-        return $this;
+        return $phonenumber;
+    }
+
+    /**
+     * @param int $index
+     * @return PhoneNumber|NULL
+     */
+    public function phoneNumber($index)
+    {
+        return array_key_exists($index, $this->phoneNumbers) ?
+            $this->phoneNumbers[$index] :
+            null;
     }
 
     /**
      * @param string $street
      * @param string $type
      * @param boolean $primary
      *
-     * @return self
+     * @return PostalAddress
      */
     public function addAddress($street, $type = '', $primary = false)
     {
@@ -142,6 +164,17 @@ public function addAddress($street, $type = '', $primary = false)
         return $address;
     }
 
+    /**
+     * @param int $index
+     * @return PostalAddress|NULL
+     */
+    public function address($index)
+    {
+        return array_key_exists($index, $this->addresses) ?
+            $this->addresses[$index] :
+            null;
+    }
+
     /**
      * @param AbstractElement $element
      * @param string $type

diff --git a/tests/ContactTest.php b/tests/ContactTest.php
@@ -27,17 +27,28 @@ public function testCreateEntryElement()
     public function testRender()
     {
         $contact = new Contact();
-        $contact->setName('Doe', 'John');
+        $contact->setName('Doe', 'John')
+            ->setNamePrefix('Dr.')
+            ->setNameSuffix('MD');
         $contact->setNote('Lorem ipsum');
-        $contact->addEmail('doe@example.org', 'home', true);
-        $contact->addEmail('doe@example.com');
-        $contact->addPhoneNumber('012 3456 789', 'home', true);
+        $email0 = $contact->addEmail('doe@example.org', 'home', true);
+        $email1 = $contact->addEmail('doe@example.com');
+        $phonenumber0 = $contact->addPhoneNumber('012 3456 789', 'home', true);
 
-        $contact->addAddress('1600 Amphitheatre Parkway', 'work', true)
+        $address0 = $contact->addAddress('1600 Amphitheatre Parkway', 'work', true)
             ->setCity('Mountain View')
             ->setRegion('California')
             ->setCountry('U.S.A.', 'US');
 
+        $this->assertSame($email0, $contact->email(0));
+        $this->assertSame($email1, $contact->email(1));
+        $this->assertNull($contact->email(2));
+
+        $this->assertSame($phonenumber0, $contact->phoneNumber(0));
+        $this->assertNull($contact->phoneNumber(1));
+        $this->assertSame($address0, $contact->address(0));
+        $this->assertNull($contact->address(1));
+
         $xmlstring = $contact->render();
         $this->assertEquals(trim(file_get_contents(__DIR__ . '/fixtures/contact.xml')), $xmlstring);
     }

diff --git a/tests/fixtures/contact.xml b/tests/fixtures/contact.xml
@@ -3,6 +3,8 @@
   <gd:name>
     <gd:givenName>John</gd:givenName>
     <gd:familyName>Doe</gd:familyName>
+    <gd:namePrefix>Dr.</gd:namePrefix>
+    <gd:nameSuffix>MD</gd:nameSuffix>
   </gd:name>
   <content>Lorem ipsum</content>
   <gd:email rel="http://schemas.google.com/g/2005#home" primary="true" address="doe@example.org"/>