Add nameOrder specification (#247)

PrinsFrank · Aug 1, 2024 · 24e7ca5 · 24e7ca5
1 parent 675cab3
commit 24e7ca5
Show file tree

Hide file tree

Showing 10 changed files with 166 additions and 0 deletions.
diff --git a/src/Country/CountryAlpha2.php b/src/Country/CountryAlpha2.php
@@ -15,6 +15,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 use PrinsFrank\Standards\NationalCallPrefix\NationalCallPrefix;
 use PrinsFrank\Standards\TopLevelDomain\CountryCodeTLD;
 
@@ -347,6 +348,23 @@ public function getNationalCallPrefix(): NationalCallPrefix
         return NationalCallPrefix::forCountry($this);
     }
 
+    public function getMostCommonNameOrder(): NameOrder
+    {
+        return match ($this) {
+            self::Cambodia,
+            self::China,
+            self::Hungary,
+            self::Japan,
+            self::Korea_Democratic_Peoples_Republic,
+            self::Korea_Republic,
+            self::Mongolia,
+            self::Singapore,
+            self::Taiwan_Province_of_China,
+            self::Viet_Nam => NameOrder::Eastern,
+            default => NameOrder::Western,
+        };
+    }
+
     /**
      * When displaying this on web pages, keep in mind the default windows fonts don't have a representation for these.
      *

diff --git a/src/Country/CountryAlpha3.php b/src/Country/CountryAlpha3.php
@@ -14,6 +14,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 use PrinsFrank\Standards\NationalCallPrefix\NationalCallPrefix;
 use PrinsFrank\Standards\TopLevelDomain\CountryCodeTLD;
 
@@ -343,6 +344,11 @@ public function getFlagEmoji(): string
         return $this->toCountryAlpha2()->getFlagEmoji();
     }
 
+    public function getMostCommonNameOrder(): NameOrder
+    {
+        return $this->toCountryAlpha2()->getMostCommonNameOrder();
+    }
+
     /** @return list<CurrencyAlpha3> */
     public function getCurrenciesAlpha3(): array
     {

diff --git a/src/Country/CountryName.php b/src/Country/CountryName.php
@@ -14,6 +14,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 use PrinsFrank\Standards\NationalCallPrefix\NationalCallPrefix;
 
 /**
@@ -333,6 +334,11 @@ public function getFlagEmoji(): string
         return $this->toCountryAlpha2()->getFlagEmoji();
     }
 
+    public function getMostCommonNameOrder(): NameOrder
+    {
+        return $this->toCountryAlpha2()->getMostCommonNameOrder();
+    }
+
     /** @return list<CurrencyAlpha3> */
     public function getCurrenciesAlpha3(): array
     {

diff --git a/src/Country/CountryNumeric.php b/src/Country/CountryNumeric.php
@@ -14,6 +14,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 use PrinsFrank\Standards\NationalCallPrefix\NationalCallPrefix;
 use PrinsFrank\Standards\TopLevelDomain\CountryCodeTLD;
 use TypeError;
@@ -359,6 +360,11 @@ public function getFlagEmoji(): string
         return $this->toCountryAlpha2()->getFlagEmoji();
     }
 
+    public function getMostCommonNameOrder(): NameOrder
+    {
+        return $this->toCountryAlpha2()->getMostCommonNameOrder();
+    }
+
     /** @return list<CurrencyAlpha3> */
     public function getCurrenciesAlpha3(): array
     {

diff --git a/src/Name/NameOrder.php b/src/Name/NameOrder.php
@@ -0,0 +1,30 @@
+<?php declare(strict_types=1);
+
+namespace PrinsFrank\Standards\Name;
+
+enum NameOrder: int
+{
+    case Eastern = 0;
+    case Western = 1;
+
+    /**
+     * In case of Mononymous names, only supply $given
+     * Patronymics and Matronymics should be given in $middle or $family depending on country/language.
+     *
+     * note: $middle is optional, if supplied/stored in two fields instead of three make sure to supply a $given and a
+     * $family name, and store any additional names in the $given field
+     */
+    public function format(?string $given, ?string $middle, ?string $family): string
+    {
+        return implode(
+            ' ',
+            array_filter(
+                match ($this) {
+                    self::Eastern => [$family, $middle, $given],
+                    self::Western => [$given, $middle, $family],
+                },
+                fn (string|null $value) => $value !== null
+            )
+        );
+    }
+}
diff --git a/tests/Unit/Country/CountryAlpha2Test.php b/tests/Unit/Country/CountryAlpha2Test.php
@@ -14,6 +14,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 
 #[CoversClass(CountryAlpha2::class)]
 class CountryAlpha2Test extends TestCase
@@ -204,4 +205,14 @@ public function testGetParentCountry(): void
         static::assertNull(CountryAlpha2::Netherlands->getParentCountry());
         static::assertSame(CountryAlpha2::Netherlands, CountryAlpha2::Aruba->getParentCountry());
     }
+
+    public function testGetMostCommonNameOrder(): void
+    {
+        foreach (CountryAlpha2::cases() as $countryAlpha2) {
+            /** @phpstan-ignore method.resultUnused */
+            $countryAlpha2->getMostCommonNameOrder();
+        }
+        static::assertSame(NameOrder::Western, CountryAlpha2::Netherlands->getMostCommonNameOrder());
+        static::assertSame(NameOrder::Eastern, CountryAlpha2::Japan->getMostCommonNameOrder());
+    }
 }
diff --git a/tests/Unit/Country/CountryAlpha3Test.php b/tests/Unit/Country/CountryAlpha3Test.php
@@ -14,6 +14,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 
 #[CoversClass(CountryAlpha3::class)]
 class CountryAlpha3Test extends TestCase
@@ -190,4 +191,13 @@ public function testGetParentCountry(): void
         static::assertNull(CountryAlpha3::Netherlands->getParentCountry());
         static::assertSame(CountryAlpha3::Netherlands, CountryAlpha3::Aruba->getParentCountry());
     }
+
+    public function testGetMostCommonNameOrder(): void
+    {
+        foreach (CountryAlpha3::cases() as $countryAlpha2) {
+            $countryAlpha2->getMostCommonNameOrder();
+        }
+        static::assertSame(NameOrder::Western, CountryAlpha3::Netherlands->getMostCommonNameOrder());
+        static::assertSame(NameOrder::Eastern, CountryAlpha3::Japan->getMostCommonNameOrder());
+    }
 }
diff --git a/tests/Unit/Country/CountryNameTest.php b/tests/Unit/Country/CountryNameTest.php
@@ -14,6 +14,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 
 #[CoversClass(CountryName::class)]
 class CountryNameTest extends TestCase
@@ -168,4 +169,13 @@ public function testGetParentCountry(): void
         static::assertNull(CountryName::Netherlands->getParentCountry());
         static::assertSame(CountryName::Netherlands, CountryName::Aruba->getParentCountry());
     }
+
+    public function testGetMostCommonNameOrder(): void
+    {
+        foreach (CountryName::cases() as $countryAlpha2) {
+            $countryAlpha2->getMostCommonNameOrder();
+        }
+        static::assertSame(NameOrder::Western, CountryName::Netherlands->getMostCommonNameOrder());
+        static::assertSame(NameOrder::Eastern, CountryName::Japan->getMostCommonNameOrder());
+    }
 }
diff --git a/tests/Unit/Country/CountryNumericTest.php b/tests/Unit/Country/CountryNumericTest.php
@@ -14,6 +14,7 @@
 use PrinsFrank\Standards\Language\LanguageAlpha3Bibliographic;
 use PrinsFrank\Standards\Language\LanguageAlpha3Extensive;
 use PrinsFrank\Standards\Language\LanguageAlpha3Terminology;
+use PrinsFrank\Standards\Name\NameOrder;
 use TypeError;
 use ValueError;
 
@@ -211,4 +212,13 @@ public function testGetParentCountry(): void
         static::assertNull(CountryNumeric::Netherlands->getParentCountry());
         static::assertSame(CountryNumeric::Netherlands, CountryNumeric::Aruba->getParentCountry());
     }
+
+    public function testGetMostCommonNameOrder(): void
+    {
+        foreach (CountryNumeric::cases() as $countryAlpha2) {
+            $countryAlpha2->getMostCommonNameOrder();
+        }
+        static::assertSame(NameOrder::Western, CountryNumeric::Netherlands->getMostCommonNameOrder());
+        static::assertSame(NameOrder::Eastern, CountryNumeric::Japan->getMostCommonNameOrder());
+    }
 }
diff --git a/tests/Unit/Name/NameOrderTest.php b/tests/Unit/Name/NameOrderTest.php
@@ -0,0 +1,59 @@
+<?php declare(strict_types=1);
+
+namespace PrinsFrank\Standards\Tests\Unit\Name;
+
+use PHPUnit\Framework\Attributes\CoversClass;
+use PHPUnit\Framework\TestCase;
+use PrinsFrank\Standards\Name\NameOrder;
+
+#[CoversClass(NameOrder::class)]
+class NameOrderTest extends TestCase
+{
+    public function testFormatPermutations(): void
+    {
+        // Different permutations - three names
+        static::assertSame('Foo Bar Boop', NameOrder::Western->format('Foo', 'Bar', 'Boop'));
+        static::assertSame('Boop Bar Foo', NameOrder::Eastern->format('Foo', 'Bar', 'Boop'));
+
+        // Different permutations - Only first and last
+        static::assertSame('Foo Boop', NameOrder::Western->format('Foo', null, 'Boop'));
+        static::assertSame('Boop Foo', NameOrder::Eastern->format('Foo', null, 'Boop'));
+
+        // Different permutations - Only first and middle
+        static::assertSame('Foo Bar', NameOrder::Western->format('Foo', 'Bar', null));
+        static::assertSame('Bar Foo', NameOrder::Eastern->format('Foo', 'Bar', null));
+
+        // Different permutations - Only middle and last
+        static::assertSame('Bar Boop', NameOrder::Western->format(null, 'Bar', 'Boop'));
+        static::assertSame('Boop Bar', NameOrder::Eastern->format(null, 'Bar', 'Boop'));
+
+        // Different permutations - Only first
+        static::assertSame('Foo', NameOrder::Western->format('Foo', null, null));
+        static::assertSame('Foo', NameOrder::Eastern->format('Foo', null, null));
+
+        // Different permutations - Only middle
+        static::assertSame('Bar', NameOrder::Western->format(null, 'Bar', null));
+        static::assertSame('Bar', NameOrder::Eastern->format(null, 'Bar', null));
+
+        // Different permutations - Only last
+        static::assertSame('Boop', NameOrder::Western->format(null, null, 'Boop'));
+        static::assertSame('Boop', NameOrder::Eastern->format(null, null, 'Boop'));
+
+        // Different permutations - None
+        static::assertSame('', NameOrder::Western->format(null, null, null));
+        static::assertSame('', NameOrder::Eastern->format(null, null, null));
+    }
+
+    public function testActualNames(): void
+    {
+        // Mononyms
+        static::assertSame('Teller', NameOrder::Eastern->format('Teller', null, null));
+        static::assertSame('Teller', NameOrder::Western->format('Teller', null, null));
+
+        // Eastern
+        static::assertSame('Abe Shinzo', NameOrder::Eastern->format('Shinzo', null, 'Abe'));
+
+        // Western
+        static::assertSame('Frank Prins', NameOrder::Western->format('Frank', null, 'Prins'));
+    }
+}