Convert PhoneNumberType & PhoneNumberFormat to enums

psalm-baseline.xml

@@ -1,15 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
-<files psalm-version="5.7.5@5390c212bab06ee230c8720c2e9c54b823db00c8">
+<files psalm-version="5.15.0@5c774aca4746caf3d239d9c8cadb9f882ca29352">
   <file src="src/PhoneNumber.php">
     <InvalidNullableReturnType>
       <code>string</code>
     </InvalidNullableReturnType>
-    <LessSpecificReturnStatement>
-      <code><![CDATA[PhoneNumberUtil::getInstance()->getNumberType($this->phoneNumber)]]></code>
-    </LessSpecificReturnStatement>
-    <MoreSpecificReturnType>
-      <code>PhoneNumberType::*</code>
-    </MoreSpecificReturnType>
     <NullableReturnStatement>
       <code><![CDATA[$this->phoneNumber->getNationalNumber()]]></code>
     </NullableReturnStatement>

src/PhoneNumber.php

@@ -50,16 +50,16 @@ public static function parse(string $phoneNumber, ?string $regionCode = null) :
     }
 
     /**
-     * @param string             $regionCode      The region code.
-     * @param PhoneNumberType::* $phoneNumberType The phone number type, defaults to a fixed line.
+     * @param string          $regionCode      The region code.
+     * @param PhoneNumberType $phoneNumberType The phone number type, defaults to a fixed line.
      *
      * @return PhoneNumber
      *
      * @throws PhoneNumberException If no example number is available for this region and type.
      */
-    public static function getExampleNumber(string $regionCode, int $phoneNumberType = PhoneNumberType::FIXED_LINE) : PhoneNumber
+    public static function getExampleNumber(string $regionCode, PhoneNumberType $phoneNumberType = PhoneNumberType::FIXED_LINE) : PhoneNumber
     {
-        $phoneNumber = PhoneNumberUtil::getInstance()->getExampleNumberForType($regionCode, $phoneNumberType);
+        $phoneNumber = PhoneNumberUtil::getInstance()->getExampleNumberForType($regionCode, $phoneNumberType->value);
 
         if ($phoneNumber === null) {
             throw new PhoneNumberException('No example number is available for the given region and type.');
@@ -165,24 +165,20 @@ public function isValidNumber() : bool
 
     /**
      * Returns the type of this phone number.
-     *
-     * @return PhoneNumberType::*
      */
-    public function getNumberType() : int
+    public function getNumberType() : PhoneNumberType
     {
-        return PhoneNumberUtil::getInstance()->getNumberType($this->phoneNumber);
+        return PhoneNumberType::from(
+            PhoneNumberUtil::getInstance()->getNumberType($this->phoneNumber),
+        );
     }
 
     /**
      * Returns a formatted string representation of this phone number.
-     *
-     * @param PhoneNumberFormat::* $format
-     *
-     * @return string
      */
-    public function format(int $format) : string
+    public function format(PhoneNumberFormat $format) : string
     {
-        return PhoneNumberUtil::getInstance()->format($this->phoneNumber, $format);
+        return PhoneNumberUtil::getInstance()->format($this->phoneNumber, $format->value);
     }
 
     /**

src/PhoneNumberFormat.php

@@ -5,9 +5,9 @@
 namespace Brick\PhoneNumber;
 
 /**
- * Constants for the phone number formats.
+ * Enum values for the phone number formats.
  */
-final class PhoneNumberFormat
+enum PhoneNumberFormat: int
 {
     /**
      * The E164 format.
@@ -17,7 +17,7 @@ final class PhoneNumberFormat
      *
      * Example: `+41446681800`.
      */
-    public const E164 = 0;
+    case E164 = 0;
 
     /**
      * The international format.
@@ -27,7 +27,7 @@ final class PhoneNumberFormat
      *
      * Example: `+41 44 668 1800`.
      */
-    public const INTERNATIONAL = 1;
+    case INTERNATIONAL = 1;
 
     /**
      * The national format.
@@ -37,7 +37,7 @@ final class PhoneNumberFormat
      *
      * Example: `044 668 1800`.
      */
-    public const NATIONAL = 2;
+    case NATIONAL = 2;
 
     /**
      * The RFC 3966 format.
@@ -46,5 +46,5 @@ final class PhoneNumberFormat
      *
      * Example: `tel:+41-44-668-1800`.
      */
-    public const RFC3966 = 3;
+    case RFC3966 = 3;
 }

src/PhoneNumberType.php

@@ -5,37 +5,37 @@
 namespace Brick\PhoneNumber;
 
 /**
- * Constants for the phone number types.
+ * Enum values for the phone number types.
  */
-final class PhoneNumberType
+enum PhoneNumberType: int
 {
     /**
      * Fixed line number.
      */
-    public const FIXED_LINE = 0;
+    case FIXED_LINE = 0;
 
     /**
      * Mobile number.
      */
-    public const MOBILE = 1;
+    case MOBILE = 1;
 
     /**
      * Fixed line or mobile number.
      *
      * In some regions (e.g. the USA), it is impossible to distinguish between fixed-line and
      * mobile numbers by looking at the phone number itself.
      */
-    public const FIXED_LINE_OR_MOBILE = 2;
+    case FIXED_LINE_OR_MOBILE = 2;
 
     /**
      * Freephone number.
      */
-    public const TOLL_FREE = 3;
+    case TOLL_FREE = 3;
 
     /**
      * Premium rate number.
      */
-    public const PREMIUM_RATE = 4;
+    case PREMIUM_RATE = 4;
 
     /**
      * Shared cost number.
@@ -45,14 +45,14 @@ final class PhoneNumberType
      *
      * @see http://en.wikipedia.org/wiki/Shared_Cost_Service
      */
-    public const SHARED_COST = 5;
+    case SHARED_COST = 5;
 
     /**
      * Voice over IP number.
      *
      * This includes TSoIP (Telephony Service over IP).
      */
-    public const VOIP = 6;
+    case VOIP = 6;
 
     /**
      * Personal number.
@@ -62,45 +62,45 @@ final class PhoneNumberType
      *
      * @see http://en.wikipedia.org/wiki/Personal_Numbers
      */
-    public const PERSONAL_NUMBER = 7;
+    case PERSONAL_NUMBER = 7;
 
     /**
      * Pager number.
      */
-    public const PAGER = 8;
+    case PAGER = 8;
 
     /**
      * Universal Access Number or Company Number.
      *
      * The number may be further routed to specific offices, but allows one number to be used for a company.
      */
-    public const UAN = 9;
+    case UAN = 9;
 
     /**
      * Unknown number type.
      *
      * A phone number is of type UNKNOWN when it does not fit any of the known patterns
      * for a specific region.
      */
-    public const UNKNOWN = 10;
+    case UNKNOWN = 10;
 
     /**
      * Emergency number.
      */
-    public const EMERGENCY = 27;
+    case EMERGENCY = 27;
 
     /**
      * Voicemail number.
      */
-    public const VOICEMAIL = 28;
+    case VOICEMAIL = 28;
 
     /**
      * Short code number.
      */
-    public const SHORT_CODE = 29;
+    case SHORT_CODE = 29;
 
     /**
      * Standard rate number.
      */
-    public const STANDARD_RATE = 30;
+    case STANDARD_RATE = 30;
 }

tests/EnumTest.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Brick\PhoneNumber\Tests;
+
+use BackedEnum;
+use Brick\PhoneNumber\PhoneNumberFormat;
+use Brick\PhoneNumber\PhoneNumberType;
+
+use PHPUnit\Framework\TestCase;
+
+/**
+ * Tests that enums are up-to-date with libphonenumber constants.
+ */
+class EnumTest extends TestCase
+{
+    /**
+     * @param class-string             $classExpected   The name or the reference libphonenumber class.
+     * @param class-string<BackedEnum> $enumClassActual The name of the enum class to test against the reference class.
+     */
+    private static function assertEnumEqualsConstants(string $classExpected, string $enumClassActual) : void
+    {
+        $expected = (new \ReflectionClass($classExpected))->getConstants();
+
+        $actual = [];
+
+        foreach ($enumClassActual::cases() as $enum) {
+            $actual[$enum->name] = $enum->value;
+        }
+
+        self::assertSame($expected, $actual);
+    }
+
+    public function testPhoneNumberFormats() : void
+    {
+        self::assertEnumEqualsConstants(\libphonenumber\PhoneNumberFormat::class, PhoneNumberFormat::class);
+    }
+
+    public function testPhoneNumberTypes() : void
+    {
+        self::assertEnumEqualsConstants(\libphonenumber\PhoneNumberType::class, PhoneNumberType::class);
+    }
+}

tests/PhoneNumberTest.php

@@ -57,12 +57,8 @@ class PhoneNumberTest extends TestCase
 
     /**
      * @dataProvider providerGetExampleNumber
-     *
-     * @param string   $regionCode
-     * @param string   $callingCode
-     * @param int|null $numberType
      */
-    public function testGetExampleNumber(string $regionCode, string $callingCode, ?int $numberType = null) : void
+    public function testGetExampleNumber(string $regionCode, string $callingCode, ?PhoneNumberType $numberType = null) : void
     {
         if ($numberType === null) {
             $phoneNumber = PhoneNumber::getExampleNumber($regionCode);
@@ -187,11 +183,8 @@ public static function providerGetRegionCode() : array
 
     /**
      * @dataProvider providerGetNumberType
-     *
-     * @param int    $numberType
-     * @param string $phoneNumber
      */
-    public function testGetNumberType(int $numberType, string $phoneNumber) : void
+    public function testGetNumberType(PhoneNumberType $numberType, string $phoneNumber) : void
     {
         self::assertSame($numberType, PhoneNumber::parse($phoneNumber)->getNumberType());
     }
@@ -374,12 +367,8 @@ public static function providerParseException() : array
 
     /**
      * @dataProvider providerFormatNumber
-     *
-     * @param string $expected
-     * @param string $phoneNumber
-     * @param int    $numberFormat
      */
-    public function testFormatNumber(string $expected, string $phoneNumber, int $numberFormat) : void
+    public function testFormatNumber(string $expected, string $phoneNumber, PhoneNumberFormat $numberFormat) : void
     {
         self::assertSame($expected, PhoneNumber::parse($phoneNumber)->format($numberFormat));
     }