refactor: Simplifies internal behavior when converting from one Alpha…

…Code type to another. (#12)

composer.json

@@ -41,7 +41,7 @@
     },
     "require": {
         "php": "^8.2",
-        "tiny-blocks/value-object": "^2"
+        "tiny-blocks/value-object": "^3"
     },
     "require-dev": {
         "phpmd/phpmd": "^2.15",

infection.json.dist

@@ -12,7 +12,8 @@
         "summary": "report/infection/logs/infection-summary.log"
     },
     "mutators": {
-        "@default": true
+        "@default": true,
+        "PublicVisibility": false
     },
     "phpUnit": {
         "configDir": "",

src/Alpha2Code.php

@@ -5,7 +5,7 @@
 namespace TinyBlocks\Country;
 
 use TinyBlocks\Country\Internal\AlphaCode;
-use TinyBlocks\Country\Internal\AlphaCodeAdapter;
+use TinyBlocks\Country\Internal\AlphaCodeMapper;
 
 /**
  * Alpha-2 code – a two-letter code that represents a country name, recommended as the general purpose code.
@@ -15,7 +15,7 @@
  */
 enum Alpha2Code: string implements AlphaCode
 {
-    use AlphaCodeAdapter;
+    use AlphaCodeMapper;
 
     case AFGHANISTAN = 'AF';
     case ALAND_ISLANDS = 'AX';
@@ -261,7 +261,7 @@ enum Alpha2Code: string implements AlphaCode
 
     public function toAlpha3(): Alpha3Code
     {
-        $value = $this->getBy(name: $this->name, inCases: Alpha3Code::cases())->value;
+        $value = $this->getBy(name: $this->name, alphaCodes: Alpha3Code::cases())->value;
         return Alpha3Code::from(value: $value);
     }
 }

src/Alpha3Code.php

@@ -5,7 +5,7 @@
 namespace TinyBlocks\Country;
 
 use TinyBlocks\Country\Internal\AlphaCode;
-use TinyBlocks\Country\Internal\AlphaCodeAdapter;
+use TinyBlocks\Country\Internal\AlphaCodeMapper;
 
 /**
  * Alpha-3 code – a three-letter code that represents a country name,
@@ -16,7 +16,7 @@
  */
 enum Alpha3Code: string implements AlphaCode
 {
-    use AlphaCodeAdapter;
+    use AlphaCodeMapper;
 
     case AFGHANISTAN = 'AFG';
     case ALAND_ISLANDS = 'ALA';
@@ -262,7 +262,7 @@ enum Alpha3Code: string implements AlphaCode
 
     public function toAlpha2(): Alpha2Code
     {
-        $value = $this->getBy(name: $this->name, inCases: Alpha2Code::cases())->value;
+        $value = $this->getBy(name: $this->name, alphaCodes: Alpha2Code::cases())->value;
         return Alpha2Code::from(value: $value);
     }
 }

src/Country.php

@@ -9,11 +9,11 @@
 use TinyBlocks\Country\Internal\Exceptions\InvalidAlphaCodeImplementation;
 use TinyBlocks\Country\Internal\Name;
 use TinyBlocks\Vo\ValueObject;
-use TinyBlocks\Vo\ValueObjectAdapter;
+use TinyBlocks\Vo\ValueObjectBehavior;
 
 final class Country implements ValueObject
 {
-    use ValueObjectAdapter;
+    use ValueObjectBehavior;
 
     private const ALPHA2_CODE_LENGTH = 2;
 

src/Internal/AlphaCode.php

@@ -5,22 +5,17 @@
 namespace TinyBlocks\Country\Internal;
 
 use BackedEnum;
+use TinyBlocks\Country\Internal\Exceptions\AlphaCodeNotFound;
 
-interface AlphaCode
+interface AlphaCode extends BackedEnum
 {
     /**
      * Retrieve an AlphaCode enum case by its name.
      *
      * @param string $name The name of the AlphaCode case to search for.
-     * @param array $inCases An array of possible enum cases to search within.
+     * @param array $alphaCodes An array of possible enum cases to search within.
      * @return BackedEnum The matching AlphaCode enum case.
+     * @throws AlphaCodeNotFound If the AlphaCode case with the given name is not found.
      */
-    public function getBy(string $name, array $inCases): BackedEnum;
-
-    /**
-     * Get the name of the AlphaCode.
-     *
-     * @return string The name of the AlphaCode.
-     */
-    public function getName(): string;
+    public function getBy(string $name, array $alphaCodes): BackedEnum;
 }

src/Internal/AlphaCodeMapper.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Country\Internal;
+
+use BackedEnum;
+use TinyBlocks\Country\Internal\Exceptions\AlphaCodeNotFound;
+
+trait AlphaCodeMapper
+{
+    public function getBy(string $name, array $alphaCodes): BackedEnum
+    {
+        foreach ($alphaCodes as $alphaCode) {
+            if ($alphaCode->name === $name) {
+                return $alphaCode;
+            }
+        }
+
+        throw new AlphaCodeNotFound(name: $name);
+    }
+}

src/Internal/Exceptions/AlphaCodeNotFound.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Country\Internal\Exceptions;
+
+use RuntimeException;
+
+final class AlphaCodeNotFound extends RuntimeException
+{
+    public function __construct(string $name)
+    {
+        $template = 'Alpha code with name <%s> not found.';
+        parent::__construct(message: sprintf($template, $name));
+    }
+}

src/Internal/Name.php

@@ -26,7 +26,7 @@ public static function from(string $name): Name
 
     public static function fromAlphaCode(AlphaCode $alphaCode): Name
     {
-        return self::from(name: $alphaCode->getName())->normalizeName();
+        return self::from(name: $alphaCode->name)->normalizeName();
     }
 
     private function normalizeName(): Name

tests/Alpha2CodeTest.php

@@ -14,7 +14,17 @@ public function testValidValues(string $value): void
     {
         /** @Given a valid Alpha2 code */
         /** @Then the value should have a length of 2 characters */
-        self::assertEquals(2, strlen($value));
+        self::assertSame(2, strlen($value));
+    }
+
+    #[DataProvider('dataProviderToAlpha3')]
+    public function testToAlpha3(Alpha2Code $alpha2Code, Alpha3Code $expected): void
+    {
+        /** @When the toAlpha3 method is called */
+        $alpha3Code = $alpha2Code->toAlpha3();
+
+        /** @Then the expected Alpha-3 code should be returned */
+        self::assertSame($expected, $alpha3Code);
     }
 
     public static function dataProvider(): array
@@ -23,4 +33,26 @@ public static function dataProvider(): array
             'value' => $alpha2Code->value
         ], Alpha2Code::cases());
     }
+
+    public static function dataProviderToAlpha3(): array
+    {
+        return [
+            'Alpha-2 code for Japan to Alpha-3'                    => [
+                'alpha2Code' => Alpha2Code::JAPAN,
+                'expected'   => Alpha3Code::JAPAN
+            ],
+            'Alpha-2 code for Brazil to Alpha-3'                   => [
+                'alpha2Code' => Alpha2Code::BRAZIL,
+                'expected'   => Alpha3Code::BRAZIL
+            ],
+            'Alpha-2 code for Switzerland to Alpha-3'              => [
+                'alpha2Code' => Alpha2Code::SWITZERLAND,
+                'expected'   => Alpha3Code::SWITZERLAND
+            ],
+            'Alpha-2 code for United States of America to Alpha-3' => [
+                'alpha2Code' => Alpha2Code::UNITED_STATES_OF_AMERICA,
+                'expected'   => Alpha3Code::UNITED_STATES_OF_AMERICA
+            ]
+        ];
+    }
 }

tests/Alpha3CodeTest.php

@@ -14,7 +14,17 @@ public function testValidValues(string $value): void
     {
         /** @Given a valid Alpha3 code */
         /** @Then the value should have a length of 3 characters */
-        self::assertEquals(3, strlen($value));
+        self::assertSame(3, strlen($value));
+    }
+
+    #[DataProvider('dataProviderToAlpha2')]
+    public function testToAlpha2(Alpha3Code $alpha3Code, Alpha2Code $expected): void
+    {
+        /** @When the toAlpha2 method is called */
+        $alpha2Code = $alpha3Code->toAlpha2();
+
+        /** @Then the expected Alpha-2 code should be returned */
+        self::assertSame($expected, $alpha2Code);
     }
 
     public static function dataProvider(): array
@@ -23,4 +33,26 @@ public static function dataProvider(): array
             'value' => $alpha3Code->value
         ], Alpha3Code::cases());
     }
+
+    public static function dataProviderToAlpha2(): array
+    {
+        return [
+            'Alpha-3 code for Japan to Alpha-2'                    => [
+                'alpha3Code' => Alpha3Code::JAPAN,
+                'expected'   => Alpha2Code::JAPAN
+            ],
+            'Alpha-3 code for Brazil to Alpha-2'                   => [
+                'alpha3Code' => Alpha3Code::BRAZIL,
+                'expected'   => Alpha2Code::BRAZIL
+            ],
+            'Alpha-3 code for Switzerland to Alpha-2'              => [
+                'alpha3Code' => Alpha3Code::SWITZERLAND,
+                'expected'   => Alpha2Code::SWITZERLAND
+            ],
+            'Alpha-3 code for United States of America to Alpha-2' => [
+                'alpha3Code' => Alpha3Code::UNITED_STATES_OF_AMERICA,
+                'expected'   => Alpha2Code::UNITED_STATES_OF_AMERICA
+            ]
+        ];
+    }
 }

tests/CountryTest.php

@@ -21,9 +21,9 @@ public function testFromAlphaCode(?string $name, AlphaCode $alphaCode, array $ex
         $actual = Country::from(alphaCode: $alphaCode, name: $name);
 
         /** @Then the Country properties should match the expected values */
-        self::assertEquals($expected['name'], $actual->name);
-        self::assertEquals($expected['alpha2Code'], $actual->alpha2);
-        self::assertEquals($expected['alpha3Code'], $actual->alpha3);
+        self::assertSame($expected['name'], $actual->name);
+        self::assertSame($expected['alpha2Code'], $actual->alpha2);
+        self::assertSame($expected['alpha3Code'], $actual->alpha3);
     }
 
     #[DataProvider('fromStringAlphaCodeDataProvider')]
@@ -34,9 +34,9 @@ public function testFromStringAlphaCode(?string $name, string $alphaCode, array
         $actual = Country::fromString(alphaCode: $alphaCode, name: $name);
 
         /** @Then the Country properties should match the expected values */
-        self::assertEquals($expected['name'], $actual->name);
-        self::assertEquals($expected['alpha2Code'], $actual->alpha2);
-        self::assertEquals($expected['alpha3Code'], $actual->alpha3);
+        self::assertSame($expected['name'], $actual->name);
+        self::assertSame($expected['alpha2Code'], $actual->alpha2);
+        self::assertSame($expected['alpha3Code'], $actual->alpha3);
     }
 
     #[DataProvider('invalidAlphaCodesDataProvider')]
@@ -71,7 +71,7 @@ public function testIfTheAlphaCodeHaveTheSameCountries(): void
         $alpha3Codes = array_map(static fn(Alpha3Code $alpha3Code): string => $alpha3Code->name, Alpha3Code::cases());
 
         /** @Then Alpha2Code and Alpha3Code should represent the same countries */
-        self::assertEquals($alpha2Codes, $alpha3Codes);
+        self::assertSame($alpha2Codes, $alpha3Codes);
     }
 
     public static function fromAlphaCodeDataProvider(): array

tests/Internal/AlphaCodeMapperTest.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TinyBlocks\Country\Internal;
+
+use PHPUnit\Framework\TestCase;
+use TinyBlocks\Country\Internal\Exceptions\AlphaCodeNotFound;
+use TinyBlocks\Country\Models\AlphaCodeXpto;
+
+final class AlphaCodeMapperTest extends TestCase
+{
+    public function testExceptionWhenAlphaCodeNotFound(): void
+    {
+        /** @Given an AlphaCode enum case */
+        $alphaCode = AlphaCodeXpto::SWITZERLAND;
+
+        /** @Then expect an AlphaCodeNotFound exception */
+        $this->expectException(AlphaCodeNotFound::class);
+        $this->expectExceptionMessage('Alpha code with name <XXX> not found.');
+
+        /** @When calling getBy with an invalid code */
+        $alphaCode->getBy(name: 'XXX', alphaCodes: $alphaCode::cases());
+    }
+}

tests/Internal/NameTest.php

@@ -30,7 +30,7 @@ public function testBuildFromAlphaCodeName(string $expected, AlphaCode $alphaCod
         $name = Name::fromAlphaCode(alphaCode: $alphaCode);
 
         /** @Then the Name value should match the expected value */
-        self::assertEquals($expected, $name->value);
+        self::assertSame($expected, $name->value);
     }
 
     public static function dataProvider(): array

tests/Models/AlphaCodeXpto.php

@@ -3,11 +3,11 @@
 namespace TinyBlocks\Country\Models;
 
 use TinyBlocks\Country\Internal\AlphaCode;
-use TinyBlocks\Country\Internal\AlphaCodeAdapter;
+use TinyBlocks\Country\Internal\AlphaCodeMapper;
 
 enum AlphaCodeXpto: string implements AlphaCode
 {
-    use AlphaCodeAdapter;
+    use AlphaCodeMapper;
 
     case SWITZERLAND = 'CH';
 }