Code and metadata changes from Google v7.3.0 (#104)

Code changes:
 - Add getExampleNumberForType that doesn't take in a region, and
   getInvalidExampleNumber
 - Update isNumberGeographical to return true for geographical mobile
   numbers.

Metadata changes:
 - Updated phone metadata for region code(s):
   BJ, BZ, CI, ET, GQ, KE, KW, ML, NO, OM, VN
 - Updated short number metadata for region code(s): KE
 - Updated geocoding data for country calling code(s):
   84 (en), 251 (en), 254 (en)
 - Updated carrier data for country calling code(s):
   84 (en), 225 (en), 229 (en), 968 (en)

Non-Google changes:
 - Updated comments in PhoneNumber and reordered code

METADATA-VERSION.txt

@@ -2,4 +2,4 @@
 # It can be a commit, branch or tag of the https://github.com/googlei18n/libphonenumber project
 #
 # For more information, look at the phing tasks in build.xml
-libphonenumber-7.2.8
+libphonenumber-7.3.0

Tests/libphonenumber/Tests/core/ExampleNumbersTest.php

@@ -51,6 +51,27 @@ public function regionList()
         return $returnList;
     }
 
+    public function numberTypes()
+    {
+        return array(
+            array(PhoneNumberType::FIXED_LINE),
+            array(PhoneNumberType::MOBILE),
+            array(PhoneNumberType::FIXED_LINE_OR_MOBILE),
+            array(PhoneNumberType::TOLL_FREE),
+            array(PhoneNumberType::PREMIUM_RATE),
+            array(PhoneNumberType::SHARED_COST),
+            array(PhoneNumberType::VOIP),
+            array(PhoneNumberType::PERSONAL_NUMBER),
+            array(PhoneNumberType::PAGER),
+            array(PhoneNumberType::UAN),
+            array(PhoneNumberType::UNKNOWN),
+            array(PhoneNumberType::EMERGENCY),
+            array(PhoneNumberType::VOICEMAIL),
+            array(PhoneNumberType::SHORT_CODE),
+            array(PhoneNumberType::STANDARD_RATE),
+        );
+    }
+
     /**
      * @dataProvider regionList
      */
@@ -230,10 +251,10 @@ public function testGlobalNetworkNumbers($callingCode)
      * @dataProvider regionList
      * @param string $regionCode
      */
-    public function testEveryRegionHasExampleNumber($regionCode)
+    public function testEveryRegionHasAnExampleNumber($regionCode)
     {
         $exampleNumber = $this->phoneNumberUtil->getExampleNumber($regionCode);
-        $this->assertNotNull($exampleNumber, "None found for region " . $regionCode);
+        $this->assertNotNull($exampleNumber, "No example number found for region " . $regionCode);
 
         /*
          * Check the number is valid
@@ -249,6 +270,26 @@ public function testEveryRegionHasExampleNumber($regionCode)
         $this->assertTrue($this->phoneNumberUtil->isValidNumberForRegion($phoneObject, $regionCode));
     }
 
+    /**
+     * @dataProvider regionList
+     * @param string $regionCode
+     */
+    public function testEveryRegionHasAnInvalidExampleNumber($regionCode)
+    {
+        $exampleNumber = $this->phoneNumberUtil->getInvalidExampleNumber($regionCode);
+        $this->assertNotNull($exampleNumber, 'No invalid example number found for region ' . $regionCode);
+    }
+
+    /**
+     * @dataProvider numberTypes
+     * @param string $numberType
+     */
+    public function testEveryTypeHasAnExampleNumber($numberType)
+    {
+        $exampleNumber = $this->phoneNumberUtil->getExampleNumberForType($numberType);
+        $this->assertNotNull($exampleNumber, 'No example number found for type ' . $numberType);
+    }
+
     /**
      * @dataProvider shortNumberRegionList
      */
@@ -268,24 +309,42 @@ public function testShortNumbersValidAndCorrectCost($regionCode)
         if (!$this->shortNumberInfo->isValidShortNumber($phoneNumber)) {
             $this->fail("Failed validation for " . (string)$phoneNumber);
         }
+    }
 
+    public function shortRegionListAndNumberCost()
+    {
         $costArray = array(
             ShortNumberCost::PREMIUM_RATE,
             ShortNumberCost::STANDARD_RATE,
             ShortNumberCost::TOLL_FREE,
             ShortNumberCost::UNKNOWN_COST
         );
 
-        foreach ($costArray as $cost) {
-            $exampleShortNumber = $this->shortNumberInfo->getExampleShortNumberForCost($regionCode, $cost);
-            if ($exampleShortNumber != '') {
-                $this->assertEquals(
-                    $cost,
-                    $this->shortNumberInfo->getExpectedCostForRegion($this->phoneNumberUtil->parse($exampleShortNumber, $regionCode), $regionCode),
-                    "Wrong cost for " . (string)$phoneNumber
-                );
+        $output = array();
+
+        foreach ($this->shortNumberRegionList() as $region) {
+            foreach ($costArray as $cost) {
+                $output[] = array($region[0], $cost);
             }
         }
+
+        return $output;
+    }
+
+    /**
+     * @dataProvider shortRegionListAndNumberCost
+     * @param $regionCode
+     * @param $cost
+     */
+    public function testShortNumberHasCorrectCost($regionCode, $cost)
+    {
+        $exampleShortNumber = $this->shortNumberInfo->getExampleShortNumberForCost($regionCode, $cost);
+        if ($exampleShortNumber != '') {
+            $phoneNumber = $this->phoneNumberUtil->parse($exampleShortNumber, $regionCode);
+            $exampleShortNumberCost = $this->shortNumberInfo->getExpectedCostForRegion($phoneNumber, $regionCode);
+
+            $this->assertEquals($cost, $exampleShortNumberCost, 'Wrong cost for ' . (string)$phoneNumber);
+        }
     }
 
     /**

docs/PhoneNumberUtil.md

@@ -196,8 +196,27 @@ var_dump($phoneNumberUtil->getExampleNumber('GB'));
 
 Returns an example `PhoneNumber` object for the `$regionCode` supplied of the `PhoneNumberType`.
 
+This also accepts the first parameter being a `PhoneNumberType`, where it will return a valid number
+for the specified number type from any country. Just leave the second parameter as null.
+
 ```php
 var_dump($phoneNumberUtil->getExampleNumberForType('GB', PhoneNumberType::MOBILE));
 // (PhoneNumber) Country Code: 44 National Number: 7400123456 ...
+
+var_dump($phoneNumberUtil->getExampleNumberForType(PhoneNumberType::MOBILE));
+// (PhoneNumber) Country Code: 1 National Number: 2015555555 ...
+```
+
+### `getInvalidExampleNumber()`
+
+Returns an example invalid `PhoneNumber` object for the `$regionCode` supplied.
+
+This can be useful for unit testing, where you want to test with an invalid number.
+The number returned will be able to be parsed. It may also be a valid short number
+for the region.
+
+```php
+var_dump($phoneNumberUtil->getInvalidExampleNumber('GB'));
+// (PhoneNumber) Country Code: 44 National Number: 121234567 ...
 ```
 

src/libphonenumber/CountryCodeSource.php

@@ -7,8 +7,26 @@
  */
 class CountryCodeSource
 {
+    /**
+     * The country_code is derived based on a phone number with a leading "+", e.g. the French
+     * number "+33 1 42 68 53 00".
+     */
     const FROM_NUMBER_WITH_PLUS_SIGN = 0;
+    /**
+     * The country_code is derived based on a phone number with a leading IDD, e.g. the French
+     * number "011 33 1 42 68 53 00", as it is dialled from US.
+     */
     const FROM_NUMBER_WITH_IDD = 1;
+    /**
+     * The country_code is derived based on a phone number without a leading "+", e.g. the French
+     * number "33 1 42 68 53 00" when defaultCountry is supplied as France.
+     */
     const FROM_NUMBER_WITHOUT_PLUS_SIGN = 2;
+    /**
+     * The country_code is derived NOT based on the phone number itself, but from the defaultCountry
+     * parameter provided in the parsing function by the clients. This happens mostly for numbers
+     * written in the national format (without country code). For example, this would be set when
+     * parsing the French number "01 42 68 53 00", when defaultCountry is supplied as France.
+     */
     const FROM_DEFAULT_COUNTRY = 3;
 }