Add PhoneNumber::getDescription()

Encapsulates PhoneNumberOfflineGeocoder.

src/PhoneNumber.php

@@ -5,6 +5,7 @@
 namespace Brick\PhoneNumber;
 
 use JsonSerializable;
+use libphonenumber\geocoding\PhoneNumberOfflineGeocoder;
 use libphonenumber\NumberParseException;
 use libphonenumber\PhoneNumberUtil;
 
@@ -212,6 +213,43 @@ public function jsonSerialize(): string
         return (string) $this;
     }
 
+    /**
+     * Returns a text description for the given phone number, in the language provided. The description might consist of
+     * the name of the country where the phone number is from, or the name of the geographical area the phone number is
+     * from if more detailed information is available.
+     *
+     * If $userRegion is set, we also consider the region of the user. If the phone number is from the same region as
+     * the user, only a lower-level description will be returned, if one exists. Otherwise, the phone number's region
+     * will be returned, with optionally some more detailed information.
+     *
+     * For example, for a user from the region "US" (United States), we would show "Mountain View, CA" for a particular
+     * number, omitting the United States from the description. For a user from the United Kingdom (region "GB"), for
+     * the same number we may show "Mountain View, CA, United States" or even just "United States".
+     *
+     * If no description is found, this method returns null.
+     *
+     * @param string      $locale     The locale for which the description should be written.
+     * @param string|null $userRegion The region code for a given user. This region will be omitted from the description
+     *                                if the phone number comes from this region. It is a two-letter uppercase CLDR
+     *                                region code.
+     *
+     * @return string|null
+     */
+    public function getDescription(string $locale, ?string $userRegion = null) : ?string
+    {
+        $description = PhoneNumberOfflineGeocoder::getInstance()->getDescriptionForNumber(
+            $this->phoneNumber,
+            $locale,
+            $userRegion
+        );
+
+        if ($description === '') {
+            return null;
+        }
+
+        return $description;
+    }
+
     /**
      * Returns a string representation of this phone number in international E164 format.
      *

tests/PhoneNumberTest.php

@@ -592,4 +592,51 @@ public function testJsonSerializable(): void
 
         self::assertSame('{"phoneNumber":"+33123000000"}', json_encode($data));
     }
+
+    /**
+     * @dataProvider providerGetDescription
+     */
+    public function testGetDescription(string $phoneNumber, string $locale, ?string $userRegion, ?string $expected) : void
+    {
+        self::assertSame($expected, PhoneNumber::parse($phoneNumber)->getDescription($locale, $userRegion));
+    }
+
+    public function providerGetDescription() : array
+    {
+        return [
+            ['+16509036313', 'EN', null, 'Mountain View, CA'],
+            ['+16509036313', 'EN', 'US', 'Mountain View, CA'],
+            ['+16509036313', 'EN', 'GB', 'United States'],
+            ['+16509036313', 'EN', 'FR', 'United States'],
+            ['+16509036313', 'EN', 'XX', 'United States'],
+            ['+16509036313', 'FR', null, 'Mountain View, CA'],
+            ['+16509036313', 'FR', 'US', 'Mountain View, CA'],
+            ['+16509036313', 'FR', 'GB', 'États-Unis'],
+            ['+16509036313', 'FR', 'FR', 'États-Unis'],
+            ['+16509036313', 'FR', 'XX', 'États-Unis'],
+
+            ['+33381251234', 'FR', null, 'Besançon'],
+            ['+33381251234', 'FR', 'FR', 'Besançon'],
+            ['+33381251234', 'FR', 'US', 'France'],
+            ['+33381251234', 'FR', 'XX', 'France'],
+            ['+33381251234', 'EN', null, 'Besançon'],
+            ['+33381251234', 'EN', 'FR', 'Besançon'],
+            ['+33381251234', 'EN', 'US', 'France'],
+            ['+33381251234', 'EN', 'XX', 'France'],
+
+            ['+33328201234', 'FR', null, 'Dunkerque'],
+            ['+33328201234', 'FR', 'FR', 'Dunkerque'],
+            ['+33328201234', 'FR', 'US', 'France'],
+            ['+33328201234', 'FR', 'XX', 'France'],
+            ['+33328201234', 'GB', null, 'Dunkirk'],
+            ['+33328201234', 'XX', null, 'Dunkirk'],
+
+            ['+41229097000', 'FR', null, 'Genève'],
+            ['+41229097000', 'FR', 'CH', 'Genève'],
+            ['+41229097000', 'FR', 'US', 'Suisse'],
+            ['+41229097000', 'XX', null, 'Geneva'],
+
+            ['+37328000000', 'XX', null, null],
+        ];
+    }
 }