Merge pull request #27 from theiconic/feature/add-given-name-getter

Add a getter to retrieve given name in original order to Name object (Fixes #21)

README.md

@@ -82,9 +82,9 @@ echo $name->getNickname();
 echo $name->getInitials();
 echo $name->getSuffix();
 
-print_r($name->getAll()); // all parts as an associative array
+print_r($name->getAll());
 
-echo $name; // re-prints the full normalised name
+echo $name;
 ```
 An empty string is returned for missing parts.
 
@@ -104,6 +104,22 @@ echo $name->getNickname(); // The Giant
 echo $name->getNickname(true); // (The Giant)
 ```
 
+#### Re-print given name in the order as entered
+You can re-print the parts that form a given name (that is first name, middle names and any initials)
+in the order they were entered in while still applying normalisation
+via `getGivenName()`:
+```php
+echo $name->getGivenName(); // J. Peter M.
+```
+
+#### Re-print full name (actual name parts only)
+You can re-print the full name, that is the given name as above followed by
+any last name parts (excluding any salutations, nick names or suffixes)
+via `getFullName()`:
+```php
+echo $name->getFullName(); // J. Peter M. Schluter
+```
+
 ### Setting Languages
 ```php
 $parser = new TheIconic\NameParser\Parser([

src/Name.php

@@ -3,6 +3,7 @@
 namespace TheIconic\NameParser;
 
 use TheIconic\NameParser\Part\AbstractPart;
+use TheIconic\NameParser\Part\GivenNamePart;
 
 class Name
 {
@@ -83,6 +84,35 @@ public function getAll(bool $format = false): array
         return $results;
     }
 
+    /**
+     * get the given name (first name, middle names and initials)
+     * in the order they were entered while still applying normalisation
+     *
+     * @return string
+     */
+    public function getGivenName(): string
+    {
+        $fullNameParts = [];
+
+        foreach ($this->parts as $part) {
+            if ($part instanceof GivenNamePart) {
+                $fullNameParts[] = $part->normalize();
+            }
+        }
+
+        return implode(' ', $fullNameParts);
+    }
+
+    /**
+     * get the given name followed by the last name (including any prefixes)
+     *
+     * @return string
+     */
+    public function getFullName(): string
+    {
+        return sprintf('%s %s', $this->getGivenName(), $this->getLastname());
+    }
+
     /**
      * get the first name
      *

src/Part/Firstname.php

@@ -2,15 +2,6 @@
 
 namespace TheIconic\NameParser\Part;
 
-class Firstname extends AbstractPart
+class Firstname extends GivenNamePart
 {
-    /**
-     * camelcase the firstname
-     *
-     * @return string
-     */
-    public function normalize(): string
-    {
-        return $this->camelcase($this->getValue());
-    }
 }

src/Part/GivenNamePart.php

@@ -0,0 +1,7 @@
+<?php
+
+namespace TheIconic\NameParser\Part;
+
+abstract class GivenNamePart extends NamePart
+{
+}

src/Part/Initial.php

@@ -2,7 +2,7 @@
 
 namespace TheIconic\NameParser\Part;
 
-class Initial extends AbstractPart
+class Initial extends GivenNamePart
 {
     /**
      * uppercase the initial

src/Part/Lastname.php

@@ -2,15 +2,6 @@
 
 namespace TheIconic\NameParser\Part;
 
-class Lastname extends AbstractPart
+class Lastname extends NamePart
 {
-    /**
-     * camelcase the lastname
-     *
-     * @return string
-     */
-    public function normalize(): string
-    {
-        return $this->camelcase($this->getValue());
-    }
 }

src/Part/Middlename.php

@@ -2,15 +2,6 @@
 
 namespace TheIconic\NameParser\Part;
 
-class Middlename extends AbstractPart
+class Middlename extends GivenNamePart
 {
-    /**
-     * camelcase the middlename for normalization
-     *
-     * @return string
-     */
-    public function normalize(): string
-    {
-        return $this->camelcase($this->getValue());
-    }
 }

src/Part/NamePart.php

@@ -0,0 +1,16 @@
+<?php
+
+namespace TheIconic\NameParser\Part;
+
+abstract class NamePart extends AbstractPart
+{
+    /**
+     * camelcase the lastname
+     *
+     * @return string
+     */
+    public function normalize(): string
+    {
+        return $this->camelcase($this->getValue());
+    }
+}

tests/NameTest.php

@@ -55,4 +55,18 @@ public function testGettingLastnameAndLastnamePrefixSeparately()
         $this->assertSame('Delft', $name->getLastname(true));
         $this->assertSame('van Delft', $name->getLastname());
     }
+
+    public function testGetGivenNameShouldReturnGivenNameInGivenOrder(): void
+    {
+        $parser = new Parser();
+        $name = $parser->parse('Schuler, J. Peter M.');
+        $this->assertSame('J. Peter M.', $name->getGivenName());
+    }
+
+    public function testGetFullNameShouldReturnTheFullNameInGivenOrder(): void
+    {
+        $parser = new Parser();
+        $name = $parser->parse('Schuler, J. Peter M.');
+        $this->assertSame('J. Peter M. Schuler', $name->getFullName());
+    }
 }