Skip to content

Commit

Permalink
Merge pull request #404 from omahm/patch-1
Browse files Browse the repository at this point in the history 
Documentation updates, typo fixes.
  • Loading branch information
@giggsey
giggsey authored Sep 29, 2020
2 parents befffd5 + c6e58bf commit 3f630e3
Showing 1 changed file with 44 additions and 13 deletions.
57 changes: 44 additions & 13 deletions src/PhoneNumberUtil.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ class PhoneNumberUtil

// The FIRST_GROUP_PATTERN was originally set to $1 but there are some countries for which the
// first group is not used in the national pattern (e.g. Argentina) so the $1 group does not match
// correctly. Therefore, we use \d, so that the first group actually used in the pattern will be
// correctly. Therefore, we use \d, so that the first group actually used in the pattern will be
// matched.
const FIRST_GROUP_PATTERN = "(\\$\\d)";
// Constants used in the formatting rules to represent the national prefix, first group and
Expand All @@ -101,7 +101,7 @@ class PhoneNumberUtil
const CC_STRING = '$CC';

// A pattern that is used to determine if the national prefix formatting rule has the first group
// only, i.e., does not start with the national prefix. Note that the pattern explicitly allows
// only, i.e, does not start with the national prefix. Note that the pattern explicitly allows
// for unbalanced parentheses.
const FIRST_GROUP_ONLY_PREFIX_PATTERN = '\\(?\\$1\\)?';
public static $PLUS_CHARS_PATTERN;
Expand All @@ -120,6 +120,7 @@ class PhoneNumberUtil

/**
* Only upper-case variants of alpha characters are stored.
*
* @var array
*/
protected static $ALPHA_MAPPINGS = array(
Expand Down Expand Up @@ -155,6 +156,7 @@ class PhoneNumberUtil
* Map of country calling codes that use a mobile token before the area code. One example of when
* this is relevant is when determining the length of the national destination code, which should
* be the length of the area code plus the length of the mobile token.
*
* @var array
*/
protected static $MOBILE_TOKEN_MAPPINGS = array();
Expand Down Expand Up @@ -182,20 +184,23 @@ class PhoneNumberUtil

/**
* For performance reasons, amalgamate both into one map.
*
* @var array
*/
protected static $ALPHA_PHONE_MAPPINGS;

/**
* Separate map of all symbols that we wish to retain when formatting alpha numbers. This
* includes digits, ASCII letters and number grouping symbols such as "-" and " ".
*
* @var array
*/
protected static $ALL_PLUS_NUMBER_GROUPING_SYMBOLS;

/**
* Simple ASCII digits map used to populate ALPHA_PHONE_MAPPINGS and
* ALL_PLUS_NUMBER_GROUPING_SYMBOLS.
*
* @var array
*/
protected static $asciiDigitMappings = array(
Expand All @@ -215,11 +220,13 @@ class PhoneNumberUtil
* Regexp of all possible ways to write extensions, for use when parsing. This will be run as a
* case-insensitive regexp match. Wide character versions are also provided after each ASCII
* version.
*
* @var String
*/
protected static $EXTN_PATTERNS_FOR_PARSING;
/**
* @var string
*
* @internal
*/
public static $EXTN_PATTERNS_FOR_MATCHING;
Expand All @@ -243,6 +250,7 @@ class PhoneNumberUtil
* have alpha-characters and punctuation.
*
* Note VALID_PUNCTUATION starts with a -, so must be the first in the range.
*
* @var string
*/
protected static $VALID_PHONE_NUMBER;
Expand Down Expand Up @@ -294,11 +302,13 @@ class PhoneNumberUtil

/**
* The set of county calling codes that map to the non-geo entity region ("001").
*
* @var array
*/
protected $countryCodesForNonGeographicalRegion = array();
/**
* The set of regions the library supports.
*
* @var array
*/
protected $supportedRegions = array();
Expand All @@ -308,11 +318,13 @@ class PhoneNumberUtil
* by that country calling code. In the case of multiple regions sharing a calling code, such as
* the NANPA regions, the one indicated with "isMainCountryForCode" in the metadata should be
* first.
*
* @var array
*/
protected $countryCallingCodeToRegionCodeMap = array();
/**
* The set of regions that share country calling code 1.
*
* @var array
*/
protected $nanpaRegions = array();
Expand Down Expand Up @@ -393,10 +405,10 @@ protected function __construct(MetadataSourceInterface $metadataSource, $country

/**
* Gets a {@link PhoneNumberUtil} instance to carry out international phone number formatting,
* parsing, or validation. The instance is loaded with phone number metadata for a number of most
* parsing or validation. The instance is loaded with phone number metadata for a number of most
* commonly used regions.
*
* <p>The {@link PhoneNumberUtil} is implemented as a singleton. Therefore, calling getInstance
* <p>The {@link PhoneNumberUtil} is implemented as a singleton. Therefore calling getInstance
* multiple times will only result in one instance being created.
*
* @param string $baseFileLocation
Expand Down Expand Up @@ -481,6 +493,7 @@ public static function initExtnPatterns()
/**
* Helper initialiser method to create the regular-expression pattern to match extensions,
* allowing the one-char extension symbols provided by {@code singleExtnSymbols}.
*
* @param string $singleExtnSymbols
* @return string
*/
Expand Down Expand Up @@ -552,6 +565,7 @@ public static function resetInstance()
/**
* Converts all alpha characters in a number to their respective digits on a keypad, but retains
* existing formatting.
*
* @param string $number
* @return string
*/
Expand All @@ -571,10 +585,10 @@ public static function convertAlphaCharactersInNumber($number)
*
* @param string $number a string of characters representing a phone number
* @param array $normalizationReplacements a mapping of characters to what they should be replaced by in
* the normalized version of the phone number
* @param bool $removeNonMatches indicates whether characters that are not able to be replaced
* the normalized version of the phone number.
* @param bool $removeNonMatches indicates whether characters that are not able to be replaced.
* should be stripped from the number. If this is false, they will be left unchanged in the number.
* @return string the normalized string version of the phone number
* @return string the normalized string version of the phone number.
*/
protected static function normalizeHelper($number, array $normalizationReplacements, $removeNonMatches)
{
Expand All @@ -595,6 +609,7 @@ protected static function normalizeHelper($number, array $normalizationReplaceme
/**
* Helper function to check if the national prefix formatting rule has the first group only, i.e.,
* does not start with the national prefix.
*
* @param string $nationalPrefixFormattingRule
* @return bool
*/
Expand Down Expand Up @@ -677,7 +692,7 @@ protected static function descHasData(PhoneNumberDesc $desc)
}

/**
* Returns the types we have metadata for based on the PhoneMetadata object passed in
* Returns the types we have metadata for based on the PhoneMetadata object passed in.
*
* @param PhoneMetadata $metadata
* @return array
Expand Down Expand Up @@ -773,6 +788,7 @@ public function getSupportedTypesForNonGeoEntity($countryCallingCode)
* entities
* <li> some geographical numbers have no area codes.
* </ul>
*
* @param PhoneNumber $number PhoneNumber object for which clients want to know the length of the area code.
* @return int the length of area code of the PhoneNumber object passed in.
*/
Expand Down Expand Up @@ -810,6 +826,7 @@ public function getLengthOfGeographicalAreaCode(PhoneNumber $number)
/**
* Returns the metadata for the given region code or {@code null} if the region code is invalid
* or unknown.
*
* @param string $regionCode
* @return null|PhoneMetadata
*/
Expand All @@ -824,6 +841,7 @@ public function getMetadataForRegion($regionCode)

/**
* Helper function to check region code is not unknown or null.
*
* @param string $regionCode
* @return bool
*/
Expand Down Expand Up @@ -856,6 +874,8 @@ public function getRegionCodeForNumber(PhoneNumber $number)
}

/**
* Returns the region code for a number from the list of region codes passing in.
*
* @param PhoneNumber $number
* @param array $regionCodes
* @return null|string
Expand Down Expand Up @@ -904,6 +924,8 @@ public function getNationalSignificantNumber(PhoneNumber $number)
}

/**
* Returns the type of number passed in i.e Toll free, premium.
*
* @param string $nationalNumber
* @param PhoneMetadata $metadata
* @return int PhoneNumberType constant
Expand Down Expand Up @@ -1012,6 +1034,7 @@ public function isNumberGeographical($phoneNumberObjOrType, $countryCallingCode

/**
* Gets the type of a valid phone number.
*
* @param PhoneNumber $number the number the phone number that we want to know the type
* @return int PhoneNumberType the type of the phone number, or UNKNOWN if it is invalid
*/
Expand Down Expand Up @@ -2188,7 +2211,7 @@ public function maybeStripNationalPrefixAndCarrierCode(&$number, PhoneMetadata $

/**
* Convenience wrapper around isPossibleNumberForTypeWithReason. Instead of returning the reason
* reason for failure, this method returns true if the number is either a possible fully-qualified
* for failure, this method returns true if the number is either a possible fully-qualified
* number (containing the area code and country code), or if the number could be a possible local
* number (with a country code, but missing an area code). Local numbers are considered possible
* if they could be possibly dialled in this format: if the area code is needed for a call to
Expand Down Expand Up @@ -2751,7 +2774,7 @@ public function isNANPACountry($regionCode)
* The original format is embedded in the country_code_source field of the PhoneNumber object
* passed in. If such information is missing, the number will be formatted into the NATIONAL
* format by default. When we don't have a formatting pattern for the number, the method returns
* the raw inptu when it is available.
* the raw input when it is available.
*
* Note this method guarantees no digit will be inserted, removed or modified as a result of
* formatting.
Expand Down Expand Up @@ -3051,7 +3074,7 @@ public function formatByPattern(PhoneNumber $number, $numberFormat, array $userD
// share a country calling code is contained by only one region for performance reasons. For
// example, for NANPA regions it will be contained in the metadata for US.
$regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
// Metadata cannot be null because the country calling code is valid
// Metadata cannot be null because the country calling code is valid.
$metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);

$formattedNumber = '';
Expand Down Expand Up @@ -3186,7 +3209,7 @@ public function getExampleNumberForType($regionCodeOrType, $type = null)
}
}

// If there wasn't an example number for a region, try the non-geographical entities
// If there wasn't an example number for a region, try the non-geographical entities.
foreach ($this->getSupportedGlobalNetworkCallingCodes() as $countryCallingCode) {
$desc = $this->getNumberDescByType($this->getMetadataForNonGeographicalRegion($countryCallingCode), $regionCodeOrType);
try {
Expand Down Expand Up @@ -3433,6 +3456,13 @@ protected function isNationalNumberSuffixOfTheOther(PhoneNumber $firstNumber, Ph
$this->stringEndsWithString($secondNumberNationalNumber, $firstNumberNationalNumber);
}

/**
* Returns true if a string ends with a given substring, false otherwise.
*
* @param string $hayStack
* @param string $needle
* @return bool
*/
protected function stringEndsWithString($hayStack, $needle)
{
$revNeedle = strrev($needle);
Expand Down Expand Up @@ -3465,7 +3495,7 @@ public function isMobileNumberPortableRegion($regionCode)
*
* Convenience wrapper around {@link #isPossibleNumberWithReason}. Instead of returning the reason
* for failure, this method returns a boolean value.
* for failure, this method returns true if the number is either a possible fully-qualified number
* For failure, this method returns true if the number is either a possible fully-qualified number
* (containing the area code and country code), or if the number could be a possible local number
* (with a country code, but missing an area code). Local numbers are considered possible if they
* could be possibly dialled in this format: if the area code is needed for a call to connect, the
Expand Down Expand Up @@ -3580,6 +3610,7 @@ public function isPossibleNumberForTypeWithReason(PhoneNumber $number, $type)
* Attempts to extract a valid number from a phone number that is too long to be valid, and resets
* the PhoneNumber object passed in to that valid version. If no valid number could be extracted,
* the PhoneNumber object passed in will not be modified.
*
* @param PhoneNumber $number a PhoneNumber object which contains a number that is too long to be valid.
* @return boolean true if a valid phone number can be successfully extracted.
*/
Expand Down

0 comments on commit 3f630e3

Please sign in to comment.