The {@link PhoneNumberUtil} is implemented as a singleton. Therefore calling getInstance
* multiple times will only result in one instance being created.
*
* @param string $baseFileLocation
* @param array|null $countryCallingCodeToRegionCodeMap
* @param MetadataLoaderInterface|null $metadataLoader
* @param MetadataSourceInterface|null $metadataSource
* @return PhoneNumberUtil instance
*/
public static function getInstance($baseFileLocation = self::META_DATA_FILE_PREFIX, array $countryCallingCodeToRegionCodeMap = null, MetadataLoaderInterface $metadataLoader = null, MetadataSourceInterface $metadataSource = null)
{
if (static::$instance === null) {
if ($countryCallingCodeToRegionCodeMap === null) {
$countryCallingCodeToRegionCodeMap = CountryCodeToRegionCodeMap::$countryCodeToRegionCodeMap;
}
if ($metadataLoader === null) {
$metadataLoader = new DefaultMetadataLoader();
}
if ($metadataSource === null) {
$metadataSource = new MultiFileMetadataSourceImpl($metadataLoader, __DIR__ . '/data/' . $baseFileLocation);
}
static::$instance = new static($metadataSource, $countryCallingCodeToRegionCodeMap);
}
return static::$instance;
}
protected function init()
{
$supportedRegions = array(array());
foreach ($this->countryCallingCodeToRegionCodeMap as $countryCode => $regionCodes) {
// We can assume that if the country calling code maps to the non-geo entity region code then
// that's the only region code it maps to.
if (count($regionCodes) === 1 && static::REGION_CODE_FOR_NON_GEO_ENTITY === $regionCodes[0]) {
// This is the subset of all country codes that map to the non-geo entity region code.
$this->countryCodesForNonGeographicalRegion[] = $countryCode;
} else {
// The supported regions set does not include the "001" non-geo entity region code.
$supportedRegions[] = $regionCodes;
}
}
$this->supportedRegions = call_user_func_array('array_merge', $supportedRegions);
// If the non-geo entity still got added to the set of supported regions it must be because
// there are entries that list the non-geo entity alongside normal regions (which is wrong).
// If we discover this, remove the non-geo entity from the set of supported regions and log.
$idx_region_code_non_geo_entity = array_search(static::REGION_CODE_FOR_NON_GEO_ENTITY, $this->supportedRegions);
if ($idx_region_code_non_geo_entity !== false) {
unset($this->supportedRegions[$idx_region_code_non_geo_entity]);
}
$this->nanpaRegions = $this->countryCallingCodeToRegionCodeMap[static::NANPA_COUNTRY_CODE];
}
/**
* @internal
*/
public static function initExtnPatterns()
{
static::$EXTN_PATTERNS_FOR_PARSING = static::createExtnPattern(true);
static::$EXTN_PATTERNS_FOR_MATCHING = static::createExtnPattern(false);
}
/**
* Helper method for constructing regular expressions for parsing. Creates an expression that
* captures up to maxLength digits.
* @param int $maxLength
* @return string
*/
private static function extnDigits($maxLength)
{
return '(' . self::DIGITS . '{1,' . $maxLength . '})';
}
/**
* Helper initialiser method to create the regular-expression pattern to match extensions.
* Note that there are currently six capturing groups for the extension itself. If this number is
* changed, MaybeStripExtension needs to be updated.
*
* @param boolean $forParsing
* @return string
*/
protected static function createExtnPattern($forParsing)
{
// We cap the maximum length of an extension based on the ambiguity of the way the extension is
// prefixed. As per ITU, the officially allowed length for extensions is actually 40, but we
// don't support this since we haven't seen real examples and this introduces many false
// interpretations as the extension labels are not standardized.
$extLimitAfterExplicitLabel = 20;
$extLimitAfterLikelyLabel = 15;
$extLimitAfterAmbiguousChar = 9;
$extLimitWhenNotSure = 6;
$possibleSeparatorsBetweenNumberAndExtLabel = "[ \xC2\xA0\\t,]*";
// Optional full stop (.) or colon, followed by zero or more spaces/tabs/commas.
$possibleCharsAfterExtLabel = "[:\\.\xEf\xBC\x8E]?[ \xC2\xA0\\t,-]*";
$optionalExtnSuffix = "#?";
// Here the extension is called out in more explicit way, i.e mentioning it obvious patterns
// like "ext.". Canonical-equivalence doesn't seem to be an option with Android java, so we
// allow two options for representing the accented o - the character itself, and one in the
// unicode decomposed form with the combining acute accent.
$explicitExtLabels = "(?:e?xt(?:ensi(?:o\xCC\x81?|\xC3\xB3))?n?|\xEF\xBD\x85?\xEF\xBD\x98\xEF\xBD\x94\xEF\xBD\x8E?|\xD0\xB4\xD0\xBE\xD0\xB1|anexo)";
// One-character symbols that can be used to indicate an extension, and less commonly used
// or more ambiguous extension labels.
$ambiguousExtLabels = "(?:[x\xEF\xBD\x98#\xEF\xBC\x83~\xEF\xBD\x9E]|int|\xEF\xBD\x89\xEF\xBD\x8E\xEF\xBD\x94)";
// When extension is not separated clearly.
$ambiguousSeparator = "[- ]+";
$rfcExtn = static::RFC3966_EXTN_PREFIX . static::extnDigits($extLimitAfterExplicitLabel);
$explicitExtn = $possibleSeparatorsBetweenNumberAndExtLabel . $explicitExtLabels
. $possibleCharsAfterExtLabel . static::extnDigits($extLimitAfterExplicitLabel)
. $optionalExtnSuffix;
$ambiguousExtn = $possibleSeparatorsBetweenNumberAndExtLabel . $ambiguousExtLabels
. $possibleCharsAfterExtLabel . static::extnDigits($extLimitAfterAmbiguousChar) . $optionalExtnSuffix;
$americanStyleExtnWithSuffix = $ambiguousSeparator . static::extnDigits($extLimitWhenNotSure) . "#";
// The first regular expression covers RFC 3966 format, where the extension is added using
// ";ext=". The second more generic where extension is mentioned with explicit labels like
// "ext:". In both the above cases we allow more numbers in extension than any other extension
// labels. The third one captures when single character extension labels or less commonly used
// labels are used. In such cases we capture fewer extension digits in order to reduce the
// chance of falsely interpreting two numbers beside each other as a number + extension. The
// fourth one covers the special case of American numbers where the extension is written with a
// hash at the end, such as "- 503#".
$extensionPattern =
$rfcExtn . "|"
. $explicitExtn . "|"
. $ambiguousExtn . "|"
. $americanStyleExtnWithSuffix;
// Additional pattern that is supported when parsing extensions, not when matching.
if ($forParsing) {
// This is same as possibleSeparatorsBetweenNumberAndExtLabel, but not matching comma as
// extension label may have it.
$possibleSeparatorsNumberExtLabelNoComma = "[ \xC2\xA0\\t]*";
// ",," is commonly used for auto dialling the extension when connected. First comma is matched
// through possibleSeparatorsBetweenNumberAndExtLabel, so we do not repeat it here. Semi-colon
// works in Iphone and Android also to pop up a button with the extension number following.
$autoDiallingAndExtLabelsFound = "(?:,{2}|;)";
$autoDiallingExtn = $possibleSeparatorsNumberExtLabelNoComma
. $autoDiallingAndExtLabelsFound . $possibleCharsAfterExtLabel
. static::extnDigits($extLimitAfterLikelyLabel) . $optionalExtnSuffix;
$onlyCommasExtn = $possibleSeparatorsNumberExtLabelNoComma
. '(?:,)+' . $possibleCharsAfterExtLabel . static::extnDigits($extLimitAfterAmbiguousChar)
. $optionalExtnSuffix;
// Here the first pattern is exclusively for extension autodialling formats which are used
// when dialling and in this case we accept longer extensions. However, the second pattern
// is more liberal on the number of commas that acts as extension labels, so we have a strict
// cap on the number of digits in such extensions.
return $extensionPattern . "|"
. $autoDiallingExtn . "|"
. $onlyCommasExtn;
}
return $extensionPattern;
}
protected static function initExtnPattern()
{
static::$EXTN_PATTERN = '/(?:' . static::$EXTN_PATTERNS_FOR_PARSING . ')$/' . static::REGEX_FLAGS;
}
protected static function initValidPhoneNumberPatterns()
{
static::initExtnPatterns();
static::$MIN_LENGTH_PHONE_NUMBER_PATTERN = '[' . static::DIGITS . ']{' . static::MIN_LENGTH_FOR_NSN . '}';
static::$VALID_PHONE_NUMBER = '[' . static::PLUS_CHARS . ']*(?:[' . static::VALID_PUNCTUATION . static::STAR_SIGN . ']*[' . static::DIGITS . ']){3,}[' . static::VALID_PUNCTUATION . static::STAR_SIGN . static::VALID_ALPHA . static::DIGITS . ']*';
static::$VALID_PHONE_NUMBER_PATTERN = '%^' . static::$MIN_LENGTH_PHONE_NUMBER_PATTERN . '$|^' . static::$VALID_PHONE_NUMBER . '(?:' . static::$EXTN_PATTERNS_FOR_PARSING . ')?$%' . static::REGEX_FLAGS;
}
protected static function initAlphaPhoneMappings()
{
static::$ALPHA_PHONE_MAPPINGS = static::$ALPHA_MAPPINGS + static::$asciiDigitMappings;
}
protected static function initValidStartCharPattern()
{
static::$VALID_START_CHAR_PATTERN = '[' . static::PLUS_CHARS . static::DIGITS . ']';
}
protected static function initMobileTokenMappings()
{
static::$MOBILE_TOKEN_MAPPINGS = array();
static::$MOBILE_TOKEN_MAPPINGS['54'] = '9';
}
protected static function initDiallableCharMappings()
{
static::$DIALLABLE_CHAR_MAPPINGS = static::$asciiDigitMappings;
static::$DIALLABLE_CHAR_MAPPINGS[static::PLUS_SIGN] = static::PLUS_SIGN;
static::$DIALLABLE_CHAR_MAPPINGS['*'] = '*';
static::$DIALLABLE_CHAR_MAPPINGS['#'] = '#';
}
/**
* Used for testing purposes only to reset the PhoneNumberUtil singleton to null.
*/
public static function resetInstance()
{
static::$instance = null;
}
/**
* Converts all alpha characters in a number to their respective digits on a keypad, but retains
* existing formatting.
*
* @param string $number
* @return string
*/
public static function convertAlphaCharactersInNumber($number)
{
if (static::$ALPHA_PHONE_MAPPINGS === null) {
static::initAlphaPhoneMappings();
}
return static::normalizeHelper($number, static::$ALPHA_PHONE_MAPPINGS, false);
}
/**
* Normalizes a string of characters representing a phone number by replacing all characters found
* in the accompanying map with the values therein, and stripping all other characters if
* removeNonMatches is true.
*
* @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.
* 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.
*/
protected static function normalizeHelper($number, array $normalizationReplacements, $removeNonMatches)
{
$normalizedNumber = '';
$strLength = mb_strlen($number, 'UTF-8');
for ($i = 0; $i < $strLength; $i++) {
$character = mb_substr($number, $i, 1, 'UTF-8');
if (isset($normalizationReplacements[mb_strtoupper($character, 'UTF-8')])) {
$normalizedNumber .= $normalizationReplacements[mb_strtoupper($character, 'UTF-8')];
} elseif (!$removeNonMatches) {
$normalizedNumber .= $character;
}
// If neither of the above are true, we remove this character.
}
return $normalizedNumber;
}
/**
* 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
*/
public static function formattingRuleHasFirstGroupOnly($nationalPrefixFormattingRule)
{
$firstGroupOnlyPrefixPatternMatcher = new Matcher(
static::FIRST_GROUP_ONLY_PREFIX_PATTERN,
$nationalPrefixFormattingRule
);
return mb_strlen($nationalPrefixFormattingRule) === 0
|| $firstGroupOnlyPrefixPatternMatcher->matches();
}
/**
* Returns all regions the library has metadata for.
*
* @return array An unordered array of the two-letter region codes for every geographical region the
* library supports
*/
public function getSupportedRegions()
{
return $this->supportedRegions;
}
/**
* Returns all global network calling codes the library has metadata for.
*
* @return array An unordered array of the country calling codes for every non-geographical entity
* the library supports
*/
public function getSupportedGlobalNetworkCallingCodes()
{
return $this->countryCodesForNonGeographicalRegion;
}
/**
* Returns all country calling codes the library has metadata for, covering both non-geographical
* entities (global network calling codes) and those used for geographical entities. The could be
* used to populate a drop-down box of country calling codes for a phone-number widget, for
* instance.
*
* @return array An unordered array of the country calling codes for every geographical and
* non-geographical entity the library supports
*/
public function getSupportedCallingCodes()
{
return array_keys($this->countryCallingCodeToRegionCodeMap);
}
/**
* Returns true if there is any possible number data set for a particular PhoneNumberDesc.
*
* @param PhoneNumberDesc $desc
* @return bool
*/
protected static function descHasPossibleNumberData(PhoneNumberDesc $desc)
{
// If this is empty, it means numbers of this type inherit from the "general desc" -> the value
// '-1' means that no numbers exist for this type.
$possibleLength = $desc->getPossibleLength();
return count($possibleLength) != 1 || $possibleLength[0] != -1;
}
/**
* Returns true if there is any data set for a particular PhoneNumberDesc.
*
* @param PhoneNumberDesc $desc
* @return bool
*/
protected static function descHasData(PhoneNumberDesc $desc)
{
// Checking most properties since we don't know what's present, since a custom build may have
// stripped just one of them (e.g. liteBuild strips exampleNumber). We don't bother checking the
// possibleLengthsLocalOnly, since if this is the only thing that's present we don't really
// support the type at all: no type-specific methods will work with only this data.
return $desc->hasExampleNumber()
|| static::descHasPossibleNumberData($desc)
|| $desc->hasNationalNumberPattern();
}
/**
* Returns the types we have metadata for based on the PhoneMetadata object passed in.
*
* @param PhoneMetadata $metadata
* @return array
*/
private function getSupportedTypesForMetadata(PhoneMetadata $metadata)
{
$types = array();
foreach (array_keys(PhoneNumberType::values()) as $type) {
if ($type === PhoneNumberType::FIXED_LINE_OR_MOBILE || $type === PhoneNumberType::UNKNOWN) {
// Never return FIXED_LINE_OR_MOBILE (it is a convenience type, and represents that a
// particular number type can't be determined) or UNKNOWN (the non-type).
continue;
}
if (self::descHasData($this->getNumberDescByType($metadata, $type))) {
$types[] = $type;
}
}
return $types;
}
/**
* Returns the types for a given region which the library has metadata for. Will not include
* FIXED_LINE_OR_MOBILE (if the numbers in this region could be classified as FIXED_LINE_OR_MOBILE,
* both FIXED_LINE and MOBILE would be present) and UNKNOWN.
*
* No types will be returned for invalid or unknown region codes.
*
* @param string $regionCode
* @return array
*/
public function getSupportedTypesForRegion($regionCode)
{
if (!$this->isValidRegionCode($regionCode)) {
return array();
}
$metadata = $this->getMetadataForRegion($regionCode);
return $this->getSupportedTypesForMetadata($metadata);
}
/**
* Returns the types for a country-code belonging to a non-geographical entity which the library
* has metadata for. Will not include FIXED_LINE_OR_MOBILE (if numbers for this non-geographical
* entity could be classified as FIXED_LINE_OR_MOBILE, both FIXED_LINE and MOBILE would be
* present) and UNKNOWN.
*
* @param int $countryCallingCode
* @return array
*/
public function getSupportedTypesForNonGeoEntity($countryCallingCode)
{
$metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode);
if ($metadata === null) {
return array();
}
return $this->getSupportedTypesForMetadata($metadata);
}
/**
* Gets the length of the geographical area code from the {@code nationalNumber} field of the
* PhoneNumber object passed in, so that clients could use it to split a national significant
* number into geographical area code and subscriber number. It works in such a way that the
* resultant subscriber number should be diallable, at least on some devices. An example of how
* this could be used:
*
*
* $phoneUtil = PhoneNumberUtil::getInstance();
* $number = $phoneUtil->parse("16502530000", "US");
* $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
*
* $areaCodeLength = $phoneUtil->getLengthOfGeographicalAreaCode($number);
* if ($areaCodeLength > 0)
* {
* $areaCode = substr($nationalSignificantNumber, 0,$areaCodeLength);
* $subscriberNumber = substr($nationalSignificantNumber, $areaCodeLength);
* } else {
* $areaCode = "";
* $subscriberNumber = $nationalSignificantNumber;
* }
*
*
* N.B.: area code is a very ambiguous concept, so the I18N team generally recommends against
* using it for most purposes, but recommends using the more general {@code nationalNumber}
* instead. Read the following carefully before deciding to use this method:
*
* $phoneUtil = PhoneNumberUtil::getInstance();
* $number = $phoneUtil->parse("18002530000", "US");
* $nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
*
* $nationalDestinationCodeLength = $phoneUtil->getLengthOfNationalDestinationCode($number);
* if ($nationalDestinationCodeLength > 0) {
* $nationalDestinationCode = substr($nationalSignificantNumber, 0, $nationalDestinationCodeLength);
* $subscriberNumber = substr($nationalSignificantNumber, $nationalDestinationCodeLength);
* } else {
* $nationalDestinationCode = "";
* $subscriberNumber = $nationalSignificantNumber;
* }
*
*
* Refer to the unit tests to see the difference between this function and
* {@link #getLengthOfGeographicalAreaCode}.
*
* @param PhoneNumber $number the PhoneNumber object for which clients want to know the length of the NDC.
* @return int the length of NDC of the PhoneNumber object passed in, which could be zero
*/
public function getLengthOfNationalDestinationCode(PhoneNumber $number)
{
if ($number->hasExtension()) {
// We don't want to alter the proto given to us, but we don't want to include the extension
// when we format it, so we copy it and clear the extension here.
$copiedProto = new PhoneNumber();
$copiedProto->mergeFrom($number);
$copiedProto->clearExtension();
} else {
$copiedProto = clone $number;
}
$nationalSignificantNumber = $this->format($copiedProto, PhoneNumberFormat::INTERNATIONAL);
$numberGroups = preg_split('/' . static::NON_DIGITS_PATTERN . '/', $nationalSignificantNumber);
// The pattern will start with "+COUNTRY_CODE " so the first group will always be the empty
// string (before the + symbol) and the second group will be the country calling code. The third
// group will be area code if it is not the last group.
if (count($numberGroups) <= 3) {
return 0;
}
if ($this->getNumberType($number) == PhoneNumberType::MOBILE) {
// For example Argentinian mobile numbers, when formatted in the international format, are in
// the form of +54 9 NDC XXXX.... As a result, we take the length of the third group (NDC) and
// add the length of the second group (which is the mobile token), which also forms part of
// the national significant number. This assumes that the mobile token is always formatted
// separately from the rest of the phone number.
$mobileToken = static::getCountryMobileToken($number->getCountryCode());
if ($mobileToken !== '') {
return mb_strlen($numberGroups[2]) + mb_strlen($numberGroups[3]);
}
}
return mb_strlen($numberGroups[2]);
}
/**
* Formats a phone number in the specified format using default rules. Note that this does not
* promise to produce a phone number that the user can dial from where they are - although we do
* format in either 'national' or 'international' format depending on what the client asks for, we
* do not currently support a more abbreviated format, such as for users in the same "area" who
* could potentially dial the number without area code. Note that if the phone number has a
* country calling code of 0 or an otherwise invalid country calling code, we cannot work out
* which formatting rules to apply so we return the national significant number with no formatting
* applied.
*
* @param PhoneNumber $number the phone number to be formatted
* @param int $numberFormat the PhoneNumberFormat the phone number should be formatted into
* @return string the formatted phone number
*/
public function format(PhoneNumber $number, $numberFormat)
{
if ($number->getNationalNumber() == 0 && $number->hasRawInput()) {
// Unparseable numbers that kept their raw input just use that.
// This is the only case where a number can be formatted as E164 without a
// leading '+' symbol (but the original number wasn't parseable anyway).
// TODO: Consider removing the 'if' above so that unparseable
// strings without raw input format to the empty string instead of "+00"
$rawInput = $number->getRawInput();
if (mb_strlen($rawInput) > 0) {
return $rawInput;
}
}
$formattedNumber = '';
$countryCallingCode = $number->getCountryCode();
$nationalSignificantNumber = $this->getNationalSignificantNumber($number);
if ($numberFormat == PhoneNumberFormat::E164) {
// Early exit for E164 case (even if the country calling code is invalid) since no formatting
// of the national number needs to be applied. Extensions are not formatted.
$formattedNumber .= $nationalSignificantNumber;
$this->prefixNumberWithCountryCallingCode($countryCallingCode, PhoneNumberFormat::E164, $formattedNumber);
return $formattedNumber;
}
if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
$formattedNumber .= $nationalSignificantNumber;
return $formattedNumber;
}
// Note getRegionCodeForCountryCode() is used because formatting information for regions which
// 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 (which means that the
// region code cannot be ZZ and must be one of our supported region codes).
$metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
$formattedNumber .= $this->formatNsn($nationalSignificantNumber, $metadata, $numberFormat);
$this->maybeAppendFormattedExtension($number, $metadata, $numberFormat, $formattedNumber);
$this->prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, $formattedNumber);
return $formattedNumber;
}
/**
* A helper function that is used by format and formatByPattern.
* @param int $countryCallingCode
* @param int $numberFormat PhoneNumberFormat
* @param string $formattedNumber
*/
protected function prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, &$formattedNumber)
{
switch ($numberFormat) {
case PhoneNumberFormat::E164:
$formattedNumber = static::PLUS_SIGN . $countryCallingCode . $formattedNumber;
return;
case PhoneNumberFormat::INTERNATIONAL:
$formattedNumber = static::PLUS_SIGN . $countryCallingCode . ' ' . $formattedNumber;
return;
case PhoneNumberFormat::RFC3966:
$formattedNumber = static::RFC3966_PREFIX . static::PLUS_SIGN . $countryCallingCode . '-' . $formattedNumber;
return;
case PhoneNumberFormat::NATIONAL:
default:
return;
}
}
/**
* Helper function to check the country calling code is valid.
* @param int $countryCallingCode
* @return bool
*/
protected function hasValidCountryCallingCode($countryCallingCode)
{
return isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]);
}
/**
* Returns the region code that matches the specific country calling code. In the case of no
* region code being found, ZZ will be returned. In the case of multiple regions, the one
* designated in the metadata as the "main" region for this calling code will be returned. If the
* countryCallingCode entered is valid but doesn't match a specific region (such as in the case of
* non-geographical calling codes like 800) the value "001" will be returned (corresponding to
* the value for World in the UN M.49 schema).
*
* @param int $countryCallingCode
* @return string
*/
public function getRegionCodeForCountryCode($countryCallingCode)
{
$regionCodes = isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode]) ? $this->countryCallingCodeToRegionCodeMap[$countryCallingCode] : null;
return $regionCodes === null ? static::UNKNOWN_REGION : $regionCodes[0];
}
/**
* Note in some regions, the national number can be written in two completely different ways
* depending on whether it forms part of the NATIONAL format or INTERNATIONAL format. The
* numberFormat parameter here is used to specify which format to use for those cases. If a
* carrierCode is specified, this will be inserted into the formatted string to replace $CC.
* @param string $number
* @param PhoneMetadata $metadata
* @param int $numberFormat PhoneNumberFormat
* @param null|string $carrierCode
* @return string
*/
protected function formatNsn($number, PhoneMetadata $metadata, $numberFormat, $carrierCode = null)
{
$intlNumberFormats = $metadata->intlNumberFormats();
// When the intlNumberFormats exists, we use that to format national number for the
// INTERNATIONAL format instead of using the numberDesc.numberFormats.
$availableFormats = (count($intlNumberFormats) == 0 || $numberFormat == PhoneNumberFormat::NATIONAL)
? $metadata->numberFormats()
: $metadata->intlNumberFormats();
$formattingPattern = $this->chooseFormattingPatternForNumber($availableFormats, $number);
return ($formattingPattern === null)
? $number
: $this->formatNsnUsingPattern($number, $formattingPattern, $numberFormat, $carrierCode);
}
/**
* @param NumberFormat[] $availableFormats
* @param string $nationalNumber
* @return NumberFormat|null
*/
public function chooseFormattingPatternForNumber(array $availableFormats, $nationalNumber)
{
foreach ($availableFormats as $numFormat) {
$leadingDigitsPatternMatcher = null;
$size = $numFormat->leadingDigitsPatternSize();
// We always use the last leading_digits_pattern, as it is the most detailed.
if ($size > 0) {
$leadingDigitsPatternMatcher = new Matcher(
$numFormat->getLeadingDigitsPattern($size - 1),
$nationalNumber
);
}
if ($size == 0 || $leadingDigitsPatternMatcher->lookingAt()) {
$m = new Matcher($numFormat->getPattern(), $nationalNumber);
if ($m->matches() > 0) {
return $numFormat;
}
}
}
return null;
}
/**
* Note that carrierCode is optional - if null or an empty string, no carrier code replacement
* will take place.
* @param string $nationalNumber
* @param NumberFormat $formattingPattern
* @param int $numberFormat PhoneNumberFormat
* @param null|string $carrierCode
* @return string
*/
public function formatNsnUsingPattern(
$nationalNumber,
NumberFormat $formattingPattern,
$numberFormat,
$carrierCode = null
) {
$numberFormatRule = $formattingPattern->getFormat();
$m = new Matcher($formattingPattern->getPattern(), $nationalNumber);
if ($numberFormat === PhoneNumberFormat::NATIONAL &&
$carrierCode !== null && mb_strlen($carrierCode) > 0 &&
mb_strlen($formattingPattern->getDomesticCarrierCodeFormattingRule()) > 0
) {
// Replace the $CC in the formatting rule with the desired carrier code.
$carrierCodeFormattingRule = $formattingPattern->getDomesticCarrierCodeFormattingRule();
$carrierCodeFormattingRule = str_replace(static::CC_STRING, $carrierCode, $carrierCodeFormattingRule);
// Now replace the $FG in the formatting rule with the first group and the carrier code
// combined in the appropriate way.
$firstGroupMatcher = new Matcher(static::FIRST_GROUP_PATTERN, $numberFormatRule);
$numberFormatRule = $firstGroupMatcher->replaceFirst($carrierCodeFormattingRule);
$formattedNationalNumber = $m->replaceAll($numberFormatRule);
} else {
// Use the national prefix formatting rule instead.
$nationalPrefixFormattingRule = $formattingPattern->getNationalPrefixFormattingRule();
if ($numberFormat == PhoneNumberFormat::NATIONAL &&
$nationalPrefixFormattingRule !== null &&
mb_strlen($nationalPrefixFormattingRule) > 0
) {
$firstGroupMatcher = new Matcher(static::FIRST_GROUP_PATTERN, $numberFormatRule);
$formattedNationalNumber = $m->replaceAll(
$firstGroupMatcher->replaceFirst($nationalPrefixFormattingRule)
);
} else {
$formattedNationalNumber = $m->replaceAll($numberFormatRule);
}
}
if ($numberFormat == PhoneNumberFormat::RFC3966) {
// Strip any leading punctuation.
$matcher = new Matcher(static::$SEPARATOR_PATTERN, $formattedNationalNumber);
if ($matcher->lookingAt()) {
$formattedNationalNumber = $matcher->replaceFirst('');
}
// Replace the rest with a dash between each number group.
$formattedNationalNumber = $matcher->reset($formattedNationalNumber)->replaceAll('-');
}
return $formattedNationalNumber;
}
/**
* Appends the formatted extension of a phone number to formattedNumber, if the phone number had
* an extension specified.
*
* @param PhoneNumber $number
* @param PhoneMetadata|null $metadata
* @param int $numberFormat PhoneNumberFormat
* @param string $formattedNumber
*/
protected function maybeAppendFormattedExtension(PhoneNumber $number, $metadata, $numberFormat, &$formattedNumber)
{
if ($number->hasExtension() && mb_strlen($number->getExtension()) > 0) {
if ($numberFormat === PhoneNumberFormat::RFC3966) {
$formattedNumber .= static::RFC3966_EXTN_PREFIX . $number->getExtension();
} elseif (!empty($metadata) && $metadata->hasPreferredExtnPrefix()) {
$formattedNumber .= $metadata->getPreferredExtnPrefix() . $number->getExtension();
} else {
$formattedNumber .= static::DEFAULT_EXTN_PREFIX . $number->getExtension();
}
}
}
/**
* Returns the mobile token for the provided country calling code if it has one, otherwise
* returns an empty string. A mobile token is a number inserted before the area code when dialing
* a mobile number from that country from abroad.
*
* @param int $countryCallingCode the country calling code for which we want the mobile token
* @return string the mobile token, as a string, for the given country calling code
*/
public static function getCountryMobileToken($countryCallingCode)
{
if (count(static::$MOBILE_TOKEN_MAPPINGS) === 0) {
static::initMobileTokenMappings();
}
if (array_key_exists($countryCallingCode, static::$MOBILE_TOKEN_MAPPINGS)) {
return static::$MOBILE_TOKEN_MAPPINGS[$countryCallingCode];
}
return '';
}
/**
* Checks if the number is a valid vanity (alpha) number such as 800 MICROSOFT. A valid vanity
* number will start with at least 3 digits and will have three or more alpha characters. This
* does not do region-specific checks - to work out if this number is actually valid for a region,
* it should be parsed and methods such as {@link #isPossibleNumberWithReason} and
* {@link #isValidNumber} should be used.
*
* @param string $number the number that needs to be checked
* @return bool true if the number is a valid vanity number
*/
public function isAlphaNumber($number)
{
if (!static::isViablePhoneNumber($number)) {
// Number is too short, or doesn't match the basic phone number pattern.
return false;
}
$this->maybeStripExtension($number);
return (bool)preg_match('/' . static::VALID_ALPHA_PHONE_PATTERN . '/' . static::REGEX_FLAGS, $number);
}
/**
* Checks to see if the string of characters could possibly be a phone number at all. At the
* moment, checks to see that the string begins with at least 2 digits, ignoring any punctuation
* commonly found in phone numbers.
* This method does not require the number to be normalized in advance - but does assume that
* leading non-number symbols have been removed, such as by the method extractPossibleNumber.
*
* @param string $number to be checked for viability as a phone number
* @return boolean true if the number could be a phone number of some sort, otherwise false
*/
public static function isViablePhoneNumber($number)
{
if (static::$VALID_PHONE_NUMBER_PATTERN === null) {
static::initValidPhoneNumberPatterns();
}
if (mb_strlen($number) < static::MIN_LENGTH_FOR_NSN) {
return false;
}
$validPhoneNumberPattern = static::getValidPhoneNumberPattern();
$m = preg_match($validPhoneNumberPattern, $number);
return $m > 0;
}
/**
* We append optionally the extension pattern to the end here, as a valid phone number may
* have an extension prefix appended, followed by 1 or more digits.
* @return string
*/
protected static function getValidPhoneNumberPattern()
{
return static::$VALID_PHONE_NUMBER_PATTERN;
}
/**
* Strips any extension (as in, the part of the number dialled after the call is connected,
* usually indicated with extn, ext, x or similar) from the end of the number, and returns it.
*
* @param string $number the non-normalized telephone number that we wish to strip the extension from
* @return string the phone extension
*/
protected function maybeStripExtension(&$number)
{
$matches = array();
$find = preg_match(static::$EXTN_PATTERN, $number, $matches, PREG_OFFSET_CAPTURE);
// If we find a potential extension, and the number preceding this is a viable number, we assume
// it is an extension.
if ($find > 0 && static::isViablePhoneNumber(substr($number, 0, $matches[0][1]))) {
// The numbers are captured into groups in the regular expression.
for ($i = 1, $length = count($matches); $i <= $length; $i++) {
if ($matches[$i][0] != '') {
// We go through the capturing groups until we find one that captured some digits. If none
// did, then we will return the empty string.
$extension = $matches[$i][0];
$number = substr($number, 0, $matches[0][1]);
return $extension;
}
}
}
return '';
}
/**
* Parses a string and returns it in proto buffer format. This method differs from {@link #parse}
* in that it always populates the raw_input field of the protocol buffer with numberToParse as
* well as the country_code_source field.
*
* @param string $numberToParse number that we are attempting to parse. This can contain formatting
* such as +, ( and -, as well as a phone number extension. It can also
* be provided in RFC3966 format.
* @param string $defaultRegion region that we are expecting the number to be from. This is only used
* if the number being parsed is not written in international format.
* The country calling code for the number in this case would be stored
* as that of the default region supplied.
* @param PhoneNumber $phoneNumber
* @return PhoneNumber a phone number proto buffer filled with the parsed number
*/
public function parseAndKeepRawInput($numberToParse, $defaultRegion, PhoneNumber $phoneNumber = null)
{
if ($phoneNumber === null) {
$phoneNumber = new PhoneNumber();
}
$this->parseHelper($numberToParse, $defaultRegion, true, true, $phoneNumber);
return $phoneNumber;
}
/**
* Returns an iterable over all PhoneNumberMatches in $text
*
* @param string $text
* @param string $defaultRegion
* @param AbstractLeniency $leniency Defaults to Leniency::VALID()
* @param int $maxTries Defaults to PHP_INT_MAX
* @return PhoneNumberMatcher
*/
public function findNumbers($text, $defaultRegion, AbstractLeniency $leniency = null, $maxTries = PHP_INT_MAX)
{
if ($leniency === null) {
$leniency = Leniency::VALID();
}
return new PhoneNumberMatcher($this, $text, $defaultRegion, $leniency, $maxTries);
}
/**
* Gets an AsYouTypeFormatter for the specific region.
*
* @param string $regionCode The region where the phone number is being entered.
* @return AsYouTypeFormatter
*/
public function getAsYouTypeFormatter($regionCode)
{
return new AsYouTypeFormatter($regionCode);
}
/**
* A helper function to set the values related to leading zeros in a PhoneNumber.
* @param string $nationalNumber
* @param PhoneNumber $phoneNumber
*/
public static function setItalianLeadingZerosForPhoneNumber($nationalNumber, PhoneNumber $phoneNumber)
{
if (strlen($nationalNumber) > 1 && substr($nationalNumber, 0, 1) == '0') {
$phoneNumber->setItalianLeadingZero(true);
$numberOfLeadingZeros = 1;
// Note that if the national number is all "0"s, the last "0" is not counted as a leading
// zero.
while ($numberOfLeadingZeros < (strlen($nationalNumber) - 1) &&
substr($nationalNumber, $numberOfLeadingZeros, 1) == '0') {
$numberOfLeadingZeros++;
}
if ($numberOfLeadingZeros != 1) {
$phoneNumber->setNumberOfLeadingZeros($numberOfLeadingZeros);
}
}
}
/**
* Parses a string and fills up the phoneNumber. This method is the same as the public
* parse() method, with the exception that it allows the default region to be null, for use by
* isNumberMatch(). checkRegion should be set to false if it is permitted for the default region
* to be null or unknown ("ZZ").
* @param string $numberToParse
* @param string $defaultRegion
* @param bool $keepRawInput
* @param bool $checkRegion
* @param PhoneNumber $phoneNumber
* @throws NumberParseException
*/
protected function parseHelper($numberToParse, $defaultRegion, $keepRawInput, $checkRegion, PhoneNumber $phoneNumber)
{
if ($numberToParse === null) {
throw new NumberParseException(NumberParseException::NOT_A_NUMBER, 'The phone number supplied was null.');
}
$numberToParse = trim($numberToParse);
if (mb_strlen($numberToParse) > static::MAX_INPUT_STRING_LENGTH) {
throw new NumberParseException(
NumberParseException::TOO_LONG,
'The string supplied was too long to parse.'
);
}
$nationalNumber = '';
$this->buildNationalNumberForParsing($numberToParse, $nationalNumber);
if (!static::isViablePhoneNumber($nationalNumber)) {
throw new NumberParseException(
NumberParseException::NOT_A_NUMBER,
'The string supplied did not seem to be a phone number.'
);
}
// Check the region supplied is valid, or that the extracted number starts with some sort of +
// sign so the number's region can be determined.
if ($checkRegion && !$this->checkRegionForParsing($nationalNumber, $defaultRegion)) {
throw new NumberParseException(
NumberParseException::INVALID_COUNTRY_CODE,
'Missing or invalid default region.'
);
}
if ($keepRawInput) {
$phoneNumber->setRawInput($numberToParse);
}
// Attempt to parse extension first, since it doesn't require region-specific data and we want
// to have the non-normalised number here.
$extension = $this->maybeStripExtension($nationalNumber);
if (mb_strlen($extension) > 0) {
$phoneNumber->setExtension($extension);
}
$regionMetadata = $this->getMetadataForRegion($defaultRegion);
// Check to see if the number is given in international format so we know whether this number is
// from the default region or not.
$normalizedNationalNumber = '';
try {
// TODO: This method should really just take in the string buffer that has already
// been created, and just remove the prefix, rather than taking in a string and then
// outputting a string buffer.
$countryCode = $this->maybeExtractCountryCode(
$nationalNumber,
$regionMetadata,
$normalizedNationalNumber,
$keepRawInput,
$phoneNumber
);
} catch (NumberParseException $e) {
$matcher = new Matcher(static::$PLUS_CHARS_PATTERN, $nationalNumber);
if ($e->getErrorType() == NumberParseException::INVALID_COUNTRY_CODE && $matcher->lookingAt()) {
// Strip the plus-char, and try again.
$countryCode = $this->maybeExtractCountryCode(
substr($nationalNumber, $matcher->end()),
$regionMetadata,
$normalizedNationalNumber,
$keepRawInput,
$phoneNumber
);
if ($countryCode == 0) {
throw new NumberParseException(
NumberParseException::INVALID_COUNTRY_CODE,
'Could not interpret numbers after plus-sign.'
);
}
} else {
throw new NumberParseException($e->getErrorType(), $e->getMessage(), $e);
}
}
if ($countryCode !== 0) {
$phoneNumberRegion = $this->getRegionCodeForCountryCode($countryCode);
if ($phoneNumberRegion != $defaultRegion) {
// Metadata cannot be null because the country calling code is valid.
$regionMetadata = $this->getMetadataForRegionOrCallingCode($countryCode, $phoneNumberRegion);
}
} else {
// If no extracted country calling code, use the region supplied instead. The national number
// is just the normalized version of the number we were given to parse.
$normalizedNationalNumber .= static::normalize($nationalNumber);
if ($defaultRegion !== null) {
$countryCode = $regionMetadata->getCountryCode();
$phoneNumber->setCountryCode($countryCode);
} elseif ($keepRawInput) {
$phoneNumber->clearCountryCodeSource();
}
}
if (mb_strlen($normalizedNationalNumber) < static::MIN_LENGTH_FOR_NSN) {
throw new NumberParseException(
NumberParseException::TOO_SHORT_NSN,
'The string supplied is too short to be a phone number.'
);
}
if ($regionMetadata !== null) {
$carrierCode = '';
$potentialNationalNumber = $normalizedNationalNumber;
$this->maybeStripNationalPrefixAndCarrierCode($potentialNationalNumber, $regionMetadata, $carrierCode);
// We require that the NSN remaining after stripping the national prefix and carrier code be
// long enough to be a possible length for the region. Otherwise, we don't do the stripping,
// since the original number could be a valid short number.
$validationResult = $this->testNumberLength($potentialNationalNumber, $regionMetadata);
if ($validationResult !== ValidationResult::TOO_SHORT
&& $validationResult !== ValidationResult::IS_POSSIBLE_LOCAL_ONLY
&& $validationResult !== ValidationResult::INVALID_LENGTH) {
$normalizedNationalNumber = $potentialNationalNumber;
if ($keepRawInput && mb_strlen($carrierCode) > 0) {
$phoneNumber->setPreferredDomesticCarrierCode($carrierCode);
}
}
}
$lengthOfNationalNumber = mb_strlen($normalizedNationalNumber);
if ($lengthOfNationalNumber < static::MIN_LENGTH_FOR_NSN) {
throw new NumberParseException(
NumberParseException::TOO_SHORT_NSN,
'The string supplied is too short to be a phone number.'
);
}
if ($lengthOfNationalNumber > static::MAX_LENGTH_FOR_NSN) {
throw new NumberParseException(
NumberParseException::TOO_LONG,
'The string supplied is too long to be a phone number.'
);
}
static::setItalianLeadingZerosForPhoneNumber($normalizedNationalNumber, $phoneNumber);
/*
* We have to store the National Number as a string instead of a "long" as Google do
*
* Since PHP doesn't always support 64 bit INTs, this was a float, but that had issues
* with long numbers.
*
* We have to remove the leading zeroes ourself though
*/
if ((int)$normalizedNationalNumber == 0) {
$normalizedNationalNumber = '0';
} else {
$normalizedNationalNumber = ltrim($normalizedNationalNumber, '0');
}
$phoneNumber->setNationalNumber($normalizedNationalNumber);
}
/**
* Returns a new phone number containing only the fields needed to uniquely identify a phone
* number, rather than any fields that capture the context in which the phone number was created.
* These fields correspond to those set in parse() rather than parseAndKeepRawInput()
*
* @param PhoneNumber $phoneNumberIn
* @return PhoneNumber
*/
protected static function copyCoreFieldsOnly(PhoneNumber $phoneNumberIn)
{
$phoneNumber = new PhoneNumber();
$phoneNumber->setCountryCode($phoneNumberIn->getCountryCode());
$phoneNumber->setNationalNumber($phoneNumberIn->getNationalNumber());
if (mb_strlen($phoneNumberIn->getExtension()) > 0) {
$phoneNumber->setExtension($phoneNumberIn->getExtension());
}
if ($phoneNumberIn->isItalianLeadingZero()) {
$phoneNumber->setItalianLeadingZero(true);
// This field is only relevant if there are leading zeros at all.
$phoneNumber->setNumberOfLeadingZeros($phoneNumberIn->getNumberOfLeadingZeros());
}
return $phoneNumber;
}
/**
* Converts numberToParse to a form that we can parse and write it to nationalNumber if it is
* written in RFC3966; otherwise extract a possible number out of it and write to nationalNumber.
* @param string $numberToParse
* @param string $nationalNumber
*/
protected function buildNationalNumberForParsing($numberToParse, &$nationalNumber)
{
$indexOfPhoneContext = strpos($numberToParse, static::RFC3966_PHONE_CONTEXT);
if ($indexOfPhoneContext !== false) {
$phoneContextStart = $indexOfPhoneContext + mb_strlen(static::RFC3966_PHONE_CONTEXT);
// If the phone context contains a phone number prefix, we need to capture it, whereas domains
// will be ignored.
if ($phoneContextStart < (strlen($numberToParse) - 1)
&& substr($numberToParse, $phoneContextStart, 1) == static::PLUS_SIGN) {
// Additional parameters might follow the phone context. If so, we will remove them here
// because the parameters after phone context are not important for parsing the
// phone number.
$phoneContextEnd = strpos($numberToParse, ';', $phoneContextStart);
if ($phoneContextEnd > 0) {
$nationalNumber .= substr($numberToParse, $phoneContextStart, $phoneContextEnd - $phoneContextStart);
} else {
$nationalNumber .= substr($numberToParse, $phoneContextStart);
}
}
// Now append everything between the "tel:" prefix and the phone-context. This should include
// the national number, an optional extension or isdn-subaddress component. Note we also
// handle the case when "tel:" is missing, as we have seen in some of the phone number inputs.
// In that case, we append everything from the beginning.
$indexOfRfc3966Prefix = strpos($numberToParse, static::RFC3966_PREFIX);
$indexOfNationalNumber = ($indexOfRfc3966Prefix !== false) ? $indexOfRfc3966Prefix + strlen(static::RFC3966_PREFIX) : 0;
$nationalNumber .= substr(
$numberToParse,
$indexOfNationalNumber,
$indexOfPhoneContext - $indexOfNationalNumber
);
} else {
// Extract a possible number from the string passed in (this strips leading characters that
// could not be the start of a phone number.)
$nationalNumber .= static::extractPossibleNumber($numberToParse);
}
// Delete the isdn-subaddress and everything after it if it is present. Note extension won't
// appear at the same time with isdn-subaddress according to paragraph 5.3 of the RFC3966 spec,
$indexOfIsdn = strpos($nationalNumber, static::RFC3966_ISDN_SUBADDRESS);
if ($indexOfIsdn > 0) {
$nationalNumber = substr($nationalNumber, 0, $indexOfIsdn);
}
// If both phone context and isdn-subaddress are absent but other parameters are present, the
// parameters are left in nationalNumber. This is because we are concerned about deleting
// content from a potential number string when there is no strong evidence that the number is
// actually written in RFC3966.
}
/**
* Attempts to extract a possible number from the string passed in. This currently strips all
* leading characters that cannot be used to start a phone number. Characters that can be used to
* start a phone number are defined in the VALID_START_CHAR_PATTERN. If none of these characters
* are found in the number passed in, an empty string is returned. This function also attempts to
* strip off any alternative extensions or endings if two or more are present, such as in the case
* of: (530) 583-6985 x302/x2303. The second extension here makes this actually two phone numbers,
* (530) 583-6985 x302 and (530) 583-6985 x2303. We remove the second extension so that the first
* number is parsed correctly.
*
* @param int $number the string that might contain a phone number
* @return string the number, stripped of any non-phone-number prefix (such as "Tel:") or an empty
* string if no character used to start phone numbers (such as + or any digit) is
* found in the number
*/
public static function extractPossibleNumber($number)
{
if (static::$VALID_START_CHAR_PATTERN === null) {
static::initValidStartCharPattern();
}
$matches = array();
$match = preg_match('/' . static::$VALID_START_CHAR_PATTERN . '/ui', $number, $matches, PREG_OFFSET_CAPTURE);
if ($match > 0) {
$number = substr($number, $matches[0][1]);
// Remove trailing non-alpha non-numerical characters.
$trailingCharsMatcher = new Matcher(static::$UNWANTED_END_CHAR_PATTERN, $number);
if ($trailingCharsMatcher->find() && $trailingCharsMatcher->start() > 0) {
$number = substr($number, 0, $trailingCharsMatcher->start());
}
// Check for extra numbers at the end.
$match = preg_match('%' . static::$SECOND_NUMBER_START_PATTERN . '%', $number, $matches, PREG_OFFSET_CAPTURE);
if ($match > 0) {
$number = substr($number, 0, $matches[0][1]);
}
return $number;
}
return '';
}
/**
* Checks to see that the region code used is valid, or if it is not valid, that the number to
* parse starts with a + symbol so that we can attempt to infer the region from the number.
* Returns false if it cannot use the region provided and the region cannot be inferred.
* @param string $numberToParse
* @param string $defaultRegion
* @return bool
*/
protected function checkRegionForParsing($numberToParse, $defaultRegion)
{
if (!$this->isValidRegionCode($defaultRegion)) {
// If the number is null or empty, we can't infer the region.
$plusCharsPatternMatcher = new Matcher(static::$PLUS_CHARS_PATTERN, $numberToParse);
if ($numberToParse === null || mb_strlen($numberToParse) == 0 || !$plusCharsPatternMatcher->lookingAt()) {
return false;
}
}
return true;
}
/**
* Tries to extract a country calling code from a number. This method will return zero if no
* country calling code is considered to be present. Country calling codes are extracted in the
* following ways:
* Use {@link #formatNationalNumberWithCarrierCode} instead if the carrier code passed in * should take precedence over the number's {@code preferredDomesticCarrierCode} when formatting. * * @param PhoneNumber $number the phone number to be formatted * @param string $fallbackCarrierCode the carrier selection code to be used, if none is found in the * phone number itself * @return string the formatted phone number in national format for dialing using the number's * {@code preferredDomesticCarrierCode}, or the {@code fallbackCarrierCode} passed in if * none is found */ public function formatNationalNumberWithPreferredCarrierCode(PhoneNumber $number, $fallbackCarrierCode) { return $this->formatNationalNumberWithCarrierCode( $number, // Historically, we set this to an empty string when parsing with raw input if none was // found in the input string. However, this doesn't result in a number we can dial. For this // reason, we treat the empty string the same as if it isn't set at all. mb_strlen($number->getPreferredDomesticCarrierCode()) > 0 ? $number->getPreferredDomesticCarrierCode() : $fallbackCarrierCode ); } /** * Returns true if the number can be dialled from outside the region, or unknown. If the number * can only be dialled from within the region, returns false. Does not check the number is a valid * number. Note that, at the moment, this method does not handle short numbers (which are * currently all presumed to not be diallable from outside their country). * * @param PhoneNumber $number the phone-number for which we want to know whether it is diallable from outside the region * @return bool */ public function canBeInternationallyDialled(PhoneNumber $number) { $metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number)); if ($metadata === null) { // Note numbers belonging to non-geographical entities (e.g. +800 numbers) are always // internationally diallable, and will be caught here. return true; } $nationalSignificantNumber = $this->getNationalSignificantNumber($number); return !$this->isNumberMatchingDesc($nationalSignificantNumber, $metadata->getNoInternationalDialling()); } /** * Normalizes a string of characters representing a phone number. This strips all characters which * are not diallable on a mobile phone keypad (including all non-ASCII digits). * * @param string $number a string of characters representing a phone number * @return string the normalized string version of the phone number */ public static function normalizeDiallableCharsOnly($number) { if (count(static::$DIALLABLE_CHAR_MAPPINGS) === 0) { static::initDiallableCharMappings(); } return static::normalizeHelper($number, static::$DIALLABLE_CHAR_MAPPINGS, true /* remove non matches */); } /** * Formats a phone number for out-of-country dialing purposes. * * Note that in this version, if the number was entered originally using alpha characters and * this version of the number is stored in raw_input, this representation of the number will be * used rather than the digit representation. Grouping information, as specified by characters * such as "-" and " ", will be retained. * *
Caveats:
*If the number itself has a country calling code of zero or an otherwise invalid country * calling code, then we return the number with no formatting applied. * *
Note this function takes care of the case for calling inside of NANPA and between Russia and * Kazakhstan (who share the same country calling code). In those cases, no international prefix * is used. For regions which have multiple international prefixes, the number in its * INTERNATIONAL format will be returned instead. * * @param PhoneNumber $number the phone number to be formatted * @param string $regionCallingFrom the region where the call is being placed * @return string the formatted phone number */ public function formatOutOfCountryCallingNumber(PhoneNumber $number, $regionCallingFrom) { if (!$this->isValidRegionCode($regionCallingFrom)) { return $this->format($number, PhoneNumberFormat::INTERNATIONAL); } $countryCallingCode = $number->getCountryCode(); $nationalSignificantNumber = $this->getNationalSignificantNumber($number); if (!$this->hasValidCountryCallingCode($countryCallingCode)) { return $nationalSignificantNumber; } if ($countryCallingCode == static::NANPA_COUNTRY_CODE) { if ($this->isNANPACountry($regionCallingFrom)) { // For NANPA regions, return the national format for these regions but prefix it with the // country calling code. return $countryCallingCode . ' ' . $this->format($number, PhoneNumberFormat::NATIONAL); } } elseif ($countryCallingCode == $this->getCountryCodeForValidRegion($regionCallingFrom)) { // If regions share a country calling code, the country calling code need not be dialled. // This also applies when dialling within a region, so this if clause covers both these cases. // Technically this is the case for dialling from La Reunion to other overseas departments of // France (French Guiana, Martinique, Guadeloupe), but not vice versa - so we don't cover this // edge case for now and for those cases return the version including country calling code. // Details here: http://www.petitfute.com/voyage/225-info-pratiques-reunion return $this->format($number, PhoneNumberFormat::NATIONAL); } // Metadata cannot be null because we checked 'isValidRegionCode()' above. $metadataForRegionCallingFrom = $this->getMetadataForRegion($regionCallingFrom); $internationalPrefix = $metadataForRegionCallingFrom->getInternationalPrefix(); // For regions that have multiple international prefixes, the international format of the // number is returned, unless there is a preferred international prefix. $internationalPrefixForFormatting = ''; $uniqueInternationalPrefixMatcher = new Matcher(static::SINGLE_INTERNATIONAL_PREFIX, $internationalPrefix); if ($uniqueInternationalPrefixMatcher->matches()) { $internationalPrefixForFormatting = $internationalPrefix; } elseif ($metadataForRegionCallingFrom->hasPreferredInternationalPrefix()) { $internationalPrefixForFormatting = $metadataForRegionCallingFrom->getPreferredInternationalPrefix(); } $regionCode = $this->getRegionCodeForCountryCode($countryCallingCode); // Metadata cannot be null because the country calling code is valid. $metadataForRegion = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode); $formattedNationalNumber = $this->formatNsn( $nationalSignificantNumber, $metadataForRegion, PhoneNumberFormat::INTERNATIONAL ); $formattedNumber = $formattedNationalNumber; $this->maybeAppendFormattedExtension( $number, $metadataForRegion, PhoneNumberFormat::INTERNATIONAL, $formattedNumber ); if (mb_strlen($internationalPrefixForFormatting) > 0) { $formattedNumber = $internationalPrefixForFormatting . ' ' . $countryCallingCode . ' ' . $formattedNumber; } else { $this->prefixNumberWithCountryCallingCode( $countryCallingCode, PhoneNumberFormat::INTERNATIONAL, $formattedNumber ); } return $formattedNumber; } /** * Checks if this is a region under the North American Numbering Plan Administration (NANPA). * @param string $regionCode * @return boolean true if regionCode is one of the regions under NANPA */ public function isNANPACountry($regionCode) { return in_array($regionCode, $this->nanpaRegions); } /** * Formats a phone number using the original phone number format that the number is parsed from. * 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 input when it is available. * * Note this method guarantees no digit will be inserted, removed or modified as a result of * formatting. * * @param PhoneNumber $number the phone number that needs to be formatted in its original number format * @param string $regionCallingFrom the region whose IDD needs to be prefixed if the original number * has one * @return string the formatted phone number in its original number format */ public function formatInOriginalFormat(PhoneNumber $number, $regionCallingFrom) { if ($number->hasRawInput() && !$this->hasFormattingPatternForNumber($number)) { // We check if we have the formatting pattern because without that, we might format the number // as a group without national prefix. return $number->getRawInput(); } if (!$number->hasCountryCodeSource()) { return $this->format($number, PhoneNumberFormat::NATIONAL); } switch ($number->getCountryCodeSource()) { case CountryCodeSource::FROM_NUMBER_WITH_PLUS_SIGN: $formattedNumber = $this->format($number, PhoneNumberFormat::INTERNATIONAL); break; case CountryCodeSource::FROM_NUMBER_WITH_IDD: $formattedNumber = $this->formatOutOfCountryCallingNumber($number, $regionCallingFrom); break; case CountryCodeSource::FROM_NUMBER_WITHOUT_PLUS_SIGN: $formattedNumber = substr($this->format($number, PhoneNumberFormat::INTERNATIONAL), 1); break; case CountryCodeSource::FROM_DEFAULT_COUNTRY: // Fall-through to default case. default: $regionCode = $this->getRegionCodeForCountryCode($number->getCountryCode()); // We strip non-digits from the NDD here, and from the raw input later, so that we can // compare them easily. $nationalPrefix = $this->getNddPrefixForRegion($regionCode, true /* strip non-digits */); $nationalFormat = $this->format($number, PhoneNumberFormat::NATIONAL); if ($nationalPrefix === null || mb_strlen($nationalPrefix) == 0) { // If the region doesn't have a national prefix at all, we can safely return the national // format without worrying about a national prefix being added. $formattedNumber = $nationalFormat; break; } // Otherwise, we check if the original number was entered with a national prefix. if ($this->rawInputContainsNationalPrefix( $number->getRawInput(), $nationalPrefix, $regionCode ) ) { // If so, we can safely return the national format. $formattedNumber = $nationalFormat; break; } // Metadata cannot be null here because getNddPrefixForRegion() (above) returns null if // there is no metadata for the region. $metadata = $this->getMetadataForRegion($regionCode); $nationalNumber = $this->getNationalSignificantNumber($number); $formatRule = $this->chooseFormattingPatternForNumber($metadata->numberFormats(), $nationalNumber); // The format rule could still be null here if the national number was 0 and there was no // raw input (this should not be possible for numbers generated by the phonenumber library // as they would also not have a country calling code and we would have exited earlier). if ($formatRule === null) { $formattedNumber = $nationalFormat; break; } // When the format we apply to this number doesn't contain national prefix, we can just // return the national format. // TODO: Refactor the code below with the code in isNationalPrefixPresentIfRequired. $candidateNationalPrefixRule = $formatRule->getNationalPrefixFormattingRule(); // We assume that the first-group symbol will never be _before_ the national prefix. $indexOfFirstGroup = strpos($candidateNationalPrefixRule, '$1'); if ($indexOfFirstGroup <= 0) { $formattedNumber = $nationalFormat; break; } $candidateNationalPrefixRule = substr($candidateNationalPrefixRule, 0, $indexOfFirstGroup); $candidateNationalPrefixRule = static::normalizeDigitsOnly($candidateNationalPrefixRule); if (mb_strlen($candidateNationalPrefixRule) == 0) { // National prefix not used when formatting this number. $formattedNumber = $nationalFormat; break; } // Otherwise, we need to remove the national prefix from our output. $numFormatCopy = new NumberFormat(); $numFormatCopy->mergeFrom($formatRule); $numFormatCopy->clearNationalPrefixFormattingRule(); $numberFormats = array(); $numberFormats[] = $numFormatCopy; $formattedNumber = $this->formatByPattern($number, PhoneNumberFormat::NATIONAL, $numberFormats); break; } $rawInput = $number->getRawInput(); // If no digit is inserted/removed/modified as a result of our formatting, we return the // formatted phone number; otherwise we return the raw input the user entered. if ($formattedNumber !== null && mb_strlen($rawInput) > 0) { $normalizedFormattedNumber = static::normalizeDiallableCharsOnly($formattedNumber); $normalizedRawInput = static::normalizeDiallableCharsOnly($rawInput); if ($normalizedFormattedNumber != $normalizedRawInput) { $formattedNumber = $rawInput; } } return $formattedNumber; } /** * @param PhoneNumber $number * @return bool */ protected function hasFormattingPatternForNumber(PhoneNumber $number) { $countryCallingCode = $number->getCountryCode(); $phoneNumberRegion = $this->getRegionCodeForCountryCode($countryCallingCode); $metadata = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $phoneNumberRegion); if ($metadata === null) { return false; } $nationalNumber = $this->getNationalSignificantNumber($number); $formatRule = $this->chooseFormattingPatternForNumber($metadata->numberFormats(), $nationalNumber); return $formatRule !== null; } /** * Returns the national dialling prefix for a specific region. For example, this would be 1 for * the United States, and 0 for New Zealand. Set stripNonDigits to true to strip symbols like "~" * (which indicates a wait for a dialling tone) from the prefix returned. If no national prefix is * present, we return null. * *
Warning: Do not use this method for do-your-own formatting - for some regions, the * national dialling prefix is used only for certain types of numbers. Use the library's * formatting functions to prefix the national prefix when required. * * @param string $regionCode the region that we want to get the dialling prefix for * @param boolean $stripNonDigits true to strip non-digits from the national dialling prefix * @return string the dialling prefix for the region denoted by regionCode */ public function getNddPrefixForRegion($regionCode, $stripNonDigits) { $metadata = $this->getMetadataForRegion($regionCode); if ($metadata === null) { return null; } $nationalPrefix = $metadata->getNationalPrefix(); // If no national prefix was found, we return null. if (mb_strlen($nationalPrefix) == 0) { return null; } if ($stripNonDigits) { // Note: if any other non-numeric symbols are ever used in national prefixes, these would have // to be removed here as well. $nationalPrefix = str_replace('~', '', $nationalPrefix); } return $nationalPrefix; } /** * Check if rawInput, which is assumed to be in the national format, has a national prefix. The * national prefix is assumed to be in digits-only form. * @param string $rawInput * @param string $nationalPrefix * @param string $regionCode * @return bool */ protected function rawInputContainsNationalPrefix($rawInput, $nationalPrefix, $regionCode) { $normalizedNationalNumber = static::normalizeDigitsOnly($rawInput); if (strpos($normalizedNationalNumber, $nationalPrefix) === 0) { try { // Some Japanese numbers (e.g. 00777123) might be mistaken to contain the national prefix // when written without it (e.g. 0777123) if we just do prefix matching. To tackle that, we // check the validity of the number if the assumed national prefix is removed (777123 won't // be valid in Japan). return $this->isValidNumber( $this->parse(substr($normalizedNationalNumber, mb_strlen($nationalPrefix)), $regionCode) ); } catch (NumberParseException $e) { return false; } } return false; } /** * Tests whether a phone number matches a valid pattern. Note this doesn't verify the number * is actually in use, which is impossible to tell by just looking at a number itself. It only * verifies whether the parsed, canonicalised number is valid: not whether a particular series of * digits entered by the user is diallable from the region provided when parsing. For example, the * number +41 (0) 78 927 2696 can be parsed into a number with country code "41" and national * significant number "789272696". This is valid, while the original string is not diallable. * * @param PhoneNumber $number the phone number that we want to validate * @return boolean that indicates whether the number is of a valid pattern */ public function isValidNumber(PhoneNumber $number) { $regionCode = $this->getRegionCodeForNumber($number); return $this->isValidNumberForRegion($number, $regionCode); } /** * Tests whether a phone number is valid for a certain region. Note this doesn't verify the number * is actually in use, which is impossible to tell by just looking at a number itself. If the * country calling code is not the same as the country calling code for the region, this * immediately exits with false. After this, the specific number pattern rules for the region are * examined. This is useful for determining for example whether a particular number is valid for * Canada, rather than just a valid NANPA number. * Warning: In most cases, you want to use {@link #isValidNumber} instead. For example, this * method will mark numbers from British Crown dependencies such as the Isle of Man as invalid for * the region "GB" (United Kingdom), since it has its own region code, "IM", which may be * undesirable. * * @param PhoneNumber $number the phone number that we want to validate * @param string $regionCode the region that we want to validate the phone number for * @return boolean that indicates whether the number is of a valid pattern */ public function isValidNumberForRegion(PhoneNumber $number, $regionCode) { $countryCode = $number->getCountryCode(); $metadata = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode); if (($metadata === null) || (static::REGION_CODE_FOR_NON_GEO_ENTITY !== $regionCode && $countryCode !== $this->getCountryCodeForValidRegion($regionCode)) ) { // Either the region code was invalid, or the country calling code for this number does not // match that of the region code. return false; } $nationalSignificantNumber = $this->getNationalSignificantNumber($number); return $this->getNumberTypeHelper($nationalSignificantNumber, $metadata) != PhoneNumberType::UNKNOWN; } /** * Parses a string and returns it as a phone number in proto buffer format. The method is quite * lenient and looks for a number in the input text (raw input) and does not check whether the * string is definitely only a phone number. To do this, it ignores punctuation and white-space, * as well as any text before the number (e.g. a leading “Tel: ”) and trims the non-number bits. * It will accept a number in any format (E164, national, international etc), assuming it can * interpreted with the defaultRegion supplied. It also attempts to convert any alpha characters * into digits if it thinks this is a vanity number of the type "1800 MICROSOFT". * *
This method will throw a {@link NumberParseException} if the number is not considered to * be a possible number. Note that validation of whether the number is actually a valid number * for a particular region is not performed. This can be done separately with {@link #isValidNumber}. * *
Note this method canonicalizes the phone number such that different representations can be * easily compared, no matter what form it was originally entered in (e.g. national, * international). If you want to record context about the number being parsed, such as the raw * input that was entered, how the country code was derived etc. then call {@link * #parseAndKeepRawInput} instead. * * @param string $numberToParse number that we are attempting to parse. This can contain formatting * such as +, ( and -, as well as a phone number extension. * @param string|null $defaultRegion region that we are expecting the number to be from. This is only used * if the number being parsed is not written in international format. * The country_code for the number in this case would be stored as that * of the default region supplied. If the number is guaranteed to * start with a '+' followed by the country calling code, then * "ZZ" or null can be supplied. * @param PhoneNumber|null $phoneNumber * @param bool $keepRawInput * @return PhoneNumber a phone number proto buffer filled with the parsed number * @throws NumberParseException if the string is not considered to be a viable phone number (e.g. * too few or too many digits) or if no default region was supplied * and the number is not in international format (does not start * with +) */ public function parse($numberToParse, $defaultRegion = null, PhoneNumber $phoneNumber = null, $keepRawInput = false) { if ($phoneNumber === null) { $phoneNumber = new PhoneNumber(); } $this->parseHelper($numberToParse, $defaultRegion, $keepRawInput, true, $phoneNumber); return $phoneNumber; } /** * Formats a phone number in the specified format using client-defined formatting rules. Note that * if the phone number has a country calling code of zero or an otherwise invalid country calling * code, we cannot work out things like whether there should be a national prefix applied, or how * to format extensions, so we return the national significant number with no formatting applied. * * @param PhoneNumber $number the phone number to be formatted * @param int $numberFormat the format the phone number should be formatted into * @param array $userDefinedFormats formatting rules specified by clients * @return String the formatted phone number */ public function formatByPattern(PhoneNumber $number, $numberFormat, array $userDefinedFormats) { $countryCallingCode = $number->getCountryCode(); $nationalSignificantNumber = $this->getNationalSignificantNumber($number); if (!$this->hasValidCountryCallingCode($countryCallingCode)) { return $nationalSignificantNumber; } // Note getRegionCodeForCountryCode() is used because formatting information for regions which // 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 = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode); $formattedNumber = ''; $formattingPattern = $this->chooseFormattingPatternForNumber($userDefinedFormats, $nationalSignificantNumber); if ($formattingPattern === null) { // If no pattern above is matched, we format the number as a whole. $formattedNumber .= $nationalSignificantNumber; } else { $numFormatCopy = new NumberFormat(); // Before we do a replacement of the national prefix pattern $NP with the national prefix, we // need to copy the rule so that subsequent replacements for different numbers have the // appropriate national prefix. $numFormatCopy->mergeFrom($formattingPattern); $nationalPrefixFormattingRule = $formattingPattern->getNationalPrefixFormattingRule(); if (mb_strlen($nationalPrefixFormattingRule) > 0) { $nationalPrefix = $metadata->getNationalPrefix(); if (mb_strlen($nationalPrefix) > 0) { // Replace $NP with national prefix and $FG with the first group ($1). $nationalPrefixFormattingRule = str_replace( array(static::NP_STRING, static::FG_STRING), array($nationalPrefix, '$1'), $nationalPrefixFormattingRule ); $numFormatCopy->setNationalPrefixFormattingRule($nationalPrefixFormattingRule); } else { // We don't want to have a rule for how to format the national prefix if there isn't one. $numFormatCopy->clearNationalPrefixFormattingRule(); } } $formattedNumber .= $this->formatNsnUsingPattern($nationalSignificantNumber, $numFormatCopy, $numberFormat); } $this->maybeAppendFormattedExtension($number, $metadata, $numberFormat, $formattedNumber); $this->prefixNumberWithCountryCallingCode($countryCallingCode, $numberFormat, $formattedNumber); return $formattedNumber; } /** * Gets a valid number for the specified region. * * @param string regionCode the region for which an example number is needed * @return PhoneNumber a valid fixed-line number for the specified region. Returns null when the metadata * does not contain such information, or the region 001 is passed in. For 001 (representing * non-geographical numbers), call {@link #getExampleNumberForNonGeoEntity} instead. */ public function getExampleNumber($regionCode) { return $this->getExampleNumberForType($regionCode, PhoneNumberType::FIXED_LINE); } /** * Gets an invalid number for the specified region. This is useful for unit-testing purposes, * where you want to test what will happen with an invalid number. Note that the number that is * returned will always be able to be parsed and will have the correct country code. It may also * be a valid *short* number/code for this region. Validity checking such numbers is handled with * {@link ShortNumberInfo}. * * @param string $regionCode The region for which an example number is needed * @return PhoneNumber|null An invalid number for the specified region. Returns null when an unsupported region * or the region 001 (Earth) is passed in. */ public function getInvalidExampleNumber($regionCode) { if (!$this->isValidRegionCode($regionCode)) { return null; } // We start off with a valid fixed-line number since every country supports this. Alternatively // we could start with a different number type, since fixed-line numbers typically have a wide // breadth of valid number lengths and we may have to make it very short before we get an // invalid number. $desc = $this->getNumberDescByType($this->getMetadataForRegion($regionCode), PhoneNumberType::FIXED_LINE); if ($desc->getExampleNumber() == '') { // This shouldn't happen; we have a test for this. return null; } $exampleNumber = $desc->getExampleNumber(); // Try and make the number invalid. We do this by changing the length. We try reducing the // length of the number, since currently no region has a number that is the same length as // MIN_LENGTH_FOR_NSN. This is probably quicker than making the number longer, which is another // alternative. We could also use the possible number pattern to extract the possible lengths of // the number to make this faster, but this method is only for unit-testing so simplicity is // preferred to performance. We don't want to return a number that can't be parsed, so we check // the number is long enough. We try all possible lengths because phone number plans often have // overlapping prefixes so the number 123456 might be valid as a fixed-line number, and 12345 as // a mobile number. It would be faster to loop in a different order, but we prefer numbers that // look closer to real numbers (and it gives us a variety of different lengths for the resulting // phone numbers - otherwise they would all be MIN_LENGTH_FOR_NSN digits long.) for ($phoneNumberLength = mb_strlen($exampleNumber) - 1; $phoneNumberLength >= static::MIN_LENGTH_FOR_NSN; $phoneNumberLength--) { $numberToTry = mb_substr($exampleNumber, 0, $phoneNumberLength); try { $possiblyValidNumber = $this->parse($numberToTry, $regionCode); if (!$this->isValidNumber($possiblyValidNumber)) { return $possiblyValidNumber; } } catch (NumberParseException $e) { // Shouldn't happen: we have already checked the length, we know example numbers have // only valid digits, and we know the region code is fine. } } // We have a test to check that this doesn't happen for any of our supported regions. return null; } /** * Gets a valid number for the specified region and number type. * * @param string|int $regionCodeOrType the region for which an example number is needed * @param int $type the PhoneNumberType of number that is needed * @return PhoneNumber|null a valid number for the specified region and type. Returns null when the metadata * does not contain such information or if an invalid region or region 001 was entered. * For 001 (representing non-geographical numbers), call * {@link #getExampleNumberForNonGeoEntity} instead. * * If $regionCodeOrType is the only parameter supplied, then a valid number for the specified number type * will be returned that may belong to any country. */ public function getExampleNumberForType($regionCodeOrType, $type = null) { if ($regionCodeOrType !== null && $type === null) { /* * Gets a valid number for the specified number type (it may belong to any country). */ foreach ($this->getSupportedRegions() as $regionCode) { $exampleNumber = $this->getExampleNumberForType($regionCode, $regionCodeOrType); if ($exampleNumber !== null) { return $exampleNumber; } } // 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 { if ($desc->getExampleNumber() != '') { return $this->parse('+' . $countryCallingCode . $desc->getExampleNumber(), static::UNKNOWN_REGION); } } catch (NumberParseException $e) { // noop } } // There are no example numbers of this type for any country in the library. return null; } // Check the region code is valid. if (!$this->isValidRegionCode($regionCodeOrType)) { return null; } $desc = $this->getNumberDescByType($this->getMetadataForRegion($regionCodeOrType), $type); try { if ($desc->hasExampleNumber()) { return $this->parse($desc->getExampleNumber(), $regionCodeOrType); } } catch (NumberParseException $e) { // noop } return null; } /** * @param PhoneMetadata $metadata * @param int $type PhoneNumberType * @return PhoneNumberDesc */ protected function getNumberDescByType(PhoneMetadata $metadata, $type) { switch ($type) { case PhoneNumberType::PREMIUM_RATE: return $metadata->getPremiumRate(); case PhoneNumberType::TOLL_FREE: return $metadata->getTollFree(); case PhoneNumberType::MOBILE: return $metadata->getMobile(); case PhoneNumberType::FIXED_LINE: case PhoneNumberType::FIXED_LINE_OR_MOBILE: return $metadata->getFixedLine(); case PhoneNumberType::SHARED_COST: return $metadata->getSharedCost(); case PhoneNumberType::VOIP: return $metadata->getVoip(); case PhoneNumberType::PERSONAL_NUMBER: return $metadata->getPersonalNumber(); case PhoneNumberType::PAGER: return $metadata->getPager(); case PhoneNumberType::UAN: return $metadata->getUan(); case PhoneNumberType::VOICEMAIL: return $metadata->getVoicemail(); default: return $metadata->getGeneralDesc(); } } /** * Gets a valid number for the specified country calling code for a non-geographical entity. * * @param int $countryCallingCode the country calling code for a non-geographical entity * @return PhoneNumber a valid number for the non-geographical entity. Returns null when the metadata * does not contain such information, or the country calling code passed in does not belong * to a non-geographical entity. */ public function getExampleNumberForNonGeoEntity($countryCallingCode) { $metadata = $this->getMetadataForNonGeographicalRegion($countryCallingCode); if ($metadata !== null) { // For geographical entities, fixed-line data is always present. However, for non-geographical // entities, this is not the case, so we have to go through different types to find the // example number. We don't check fixed-line or personal number since they aren't used by // non-geographical entities (if this changes, a unit-test will catch this.) /** @var PhoneNumberDesc[] $list */ $list = array( $metadata->getMobile(), $metadata->getTollFree(), $metadata->getSharedCost(), $metadata->getVoip(), $metadata->getVoicemail(), $metadata->getUan(), $metadata->getPremiumRate(), ); foreach ($list as $desc) { try { if ($desc !== null && $desc->hasExampleNumber()) { return $this->parse('+' . $countryCallingCode . $desc->getExampleNumber(), self::UNKNOWN_REGION); } } catch (NumberParseException $e) { // noop } } } return null; } /** * Takes two phone numbers and compares them for equality. * *
Returns EXACT_MATCH if the country_code, NSN, presence of a leading zero * for Italian numbers and any extension present are the same. Returns NSN_MATCH * if either or both has no region specified, and the NSNs and extensions are * the same. Returns SHORT_NSN_MATCH if either or both has no region specified, * or the region specified is the same, and one NSN could be a shorter version * of the other number. This includes the case where one has an extension * specified, and the other does not. Returns NO_MATCH otherwise. For example, * the numbers +1 345 657 1234 and 657 1234 are a SHORT_NSN_MATCH. The numbers * +1 345 657 1234 and 345 657 are a NO_MATCH. * * @param $firstNumberIn PhoneNumber|string First number to compare. If it is a * string it can contain formatting, and can have country calling code specified * with + at the start. * @param $secondNumberIn PhoneNumber|string Second number to compare. If it is a * string it can contain formatting, and can have country calling code specified * with + at the start. * @throws \InvalidArgumentException * @return int {MatchType} NOT_A_NUMBER, NO_MATCH, */ public function isNumberMatch($firstNumberIn, $secondNumberIn) { if (is_string($firstNumberIn) && is_string($secondNumberIn)) { try { $firstNumberAsProto = $this->parse($firstNumberIn, static::UNKNOWN_REGION); return $this->isNumberMatch($firstNumberAsProto, $secondNumberIn); } catch (NumberParseException $e) { if ($e->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) { try { $secondNumberAsProto = $this->parse($secondNumberIn, static::UNKNOWN_REGION); return $this->isNumberMatch($secondNumberAsProto, $firstNumberIn); } catch (NumberParseException $e2) { if ($e2->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) { try { $firstNumberProto = new PhoneNumber(); $secondNumberProto = new PhoneNumber(); $this->parseHelper($firstNumberIn, null, false, false, $firstNumberProto); $this->parseHelper($secondNumberIn, null, false, false, $secondNumberProto); return $this->isNumberMatch($firstNumberProto, $secondNumberProto); } catch (NumberParseException $e3) { // Fall through and return MatchType::NOT_A_NUMBER } } } } } return MatchType::NOT_A_NUMBER; } if ($firstNumberIn instanceof PhoneNumber && is_string($secondNumberIn)) { // First see if the second number has an implicit country calling code, by attempting to parse // it. try { $secondNumberAsProto = $this->parse($secondNumberIn, static::UNKNOWN_REGION); return $this->isNumberMatch($firstNumberIn, $secondNumberAsProto); } catch (NumberParseException $e) { if ($e->getErrorType() === NumberParseException::INVALID_COUNTRY_CODE) { // The second number has no country calling code. EXACT_MATCH is no longer possible. // We parse it as if the region was the same as that for the first number, and if // EXACT_MATCH is returned, we replace this with NSN_MATCH. $firstNumberRegion = $this->getRegionCodeForCountryCode($firstNumberIn->getCountryCode()); try { if ($firstNumberRegion != static::UNKNOWN_REGION) { $secondNumberWithFirstNumberRegion = $this->parse($secondNumberIn, $firstNumberRegion); $match = $this->isNumberMatch($firstNumberIn, $secondNumberWithFirstNumberRegion); if ($match === MatchType::EXACT_MATCH) { return MatchType::NSN_MATCH; } return $match; } // If the first number didn't have a valid country calling code, then we parse the // second number without one as well. $secondNumberProto = new PhoneNumber(); $this->parseHelper($secondNumberIn, null, false, false, $secondNumberProto); return $this->isNumberMatch($firstNumberIn, $secondNumberProto); } catch (NumberParseException $e2) { // Fall-through to return NOT_A_NUMBER. } } } } if ($firstNumberIn instanceof PhoneNumber && $secondNumberIn instanceof PhoneNumber) { // We only care about the fields that uniquely define a number, so we copy these across // explicitly. $firstNumber = self::copyCoreFieldsOnly($firstNumberIn); $secondNumber = self::copyCoreFieldsOnly($secondNumberIn); // Early exit if both had extensions and these are different. if ($firstNumber->hasExtension() && $secondNumber->hasExtension() && $firstNumber->getExtension() != $secondNumber->getExtension() ) { return MatchType::NO_MATCH; } $firstNumberCountryCode = $firstNumber->getCountryCode(); $secondNumberCountryCode = $secondNumber->getCountryCode(); // Both had country_code specified. if ($firstNumberCountryCode != 0 && $secondNumberCountryCode != 0) { if ($firstNumber->equals($secondNumber)) { return MatchType::EXACT_MATCH; } if ($firstNumberCountryCode == $secondNumberCountryCode && $this->isNationalNumberSuffixOfTheOther($firstNumber, $secondNumber)) { // A SHORT_NSN_MATCH occurs if there is a difference because of the presence or absence of // an 'Italian leading zero', the presence or absence of an extension, or one NSN being a // shorter variant of the other. return MatchType::SHORT_NSN_MATCH; } // This is not a match. return MatchType::NO_MATCH; } // Checks cases where one or both country_code fields were not specified. To make equality // checks easier, we first set the country_code fields to be equal. $firstNumber->setCountryCode($secondNumberCountryCode); // If all else was the same, then this is an NSN_MATCH. if ($firstNumber->equals($secondNumber)) { return MatchType::NSN_MATCH; } if ($this->isNationalNumberSuffixOfTheOther($firstNumber, $secondNumber)) { return MatchType::SHORT_NSN_MATCH; } return MatchType::NO_MATCH; } return MatchType::NOT_A_NUMBER; } /** * Returns true when one national number is the suffix of the other or both are the same. * @param PhoneNumber $firstNumber * @param PhoneNumber $secondNumber * @return bool */ protected function isNationalNumberSuffixOfTheOther(PhoneNumber $firstNumber, PhoneNumber $secondNumber) { $firstNumberNationalNumber = trim((string)$firstNumber->getNationalNumber()); $secondNumberNationalNumber = trim((string)$secondNumber->getNationalNumber()); return $this->stringEndsWithString($firstNumberNationalNumber, $secondNumberNationalNumber) || $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); $revHayStack = strrev($hayStack); return strpos($revHayStack, $revNeedle) === 0; } /** * Returns true if the supplied region supports mobile number portability. Returns false for * invalid, unknown or regions that don't support mobile number portability. * * @param string $regionCode the region for which we want to know whether it supports mobile number * portability or not. * @return bool */ public function isMobileNumberPortableRegion($regionCode) { $metadata = $this->getMetadataForRegion($regionCode); if ($metadata === null) { return false; } return $metadata->isMobileNumberPortableRegion(); } /** * Check whether a phone number is a possible number given a number in the form of a string, and * the region where the number could be dialed from. It provides a more lenient check than * {@link #isValidNumber}. See {@link #isPossibleNumber(PhoneNumber)} for details. * * 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 * (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 * number is not considered possible without it. * * Note: There are two ways to call this method. * * isPossibleNumber(PhoneNumber $numberObject) * isPossibleNumber(string '+441174960126', string 'GB') * * @param PhoneNumber|string $number the number that needs to be checked, in the form of a string * @param string|null $regionDialingFrom the region that we are expecting the number to be dialed from. * Note this is different from the region where the number belongs. For example, the number * +1 650 253 0000 is a number that belongs to US. When written in this form, it can be * dialed from any region. When it is written as 00 1 650 253 0000, it can be dialed from any * region which uses an international dialling prefix of 00. When it is written as * 650 253 0000, it can only be dialed from within the US, and when written as 253 0000, it * can only be dialed from within a smaller area in the US (Mountain View, CA, to be more * specific). * @return boolean true if the number is possible */ public function isPossibleNumber($number, $regionDialingFrom = null) { if (is_string($number)) { try { return $this->isPossibleNumber($this->parse($number, $regionDialingFrom)); } catch (NumberParseException $e) { return false; } } else { $result = $this->isPossibleNumberWithReason($number); return $result === ValidationResult::IS_POSSIBLE || $result === ValidationResult::IS_POSSIBLE_LOCAL_ONLY; } } /** * Check whether a phone number is a possible number. It provides a more lenient check than * {@link #isValidNumber} in the following sense: *