The {@link PhoneNumberUtil} is implemented as a singleton. Therefore, calling getInstance
* multiple times will only result in one instance being created.
*
* @param array Use {@see 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, string $fallbackCarrierCode): string
{
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.
$number->hasPreferredDomesticCarrierCode() && $number->getPreferredDomesticCarrierCode() !== ''
? $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
*/
public function canBeInternationallyDialled(PhoneNumber $number): bool
{
$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(string $number): string
{
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, string $regionCallingFrom): string
{
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.
/** @var PhoneMetadata $metadataForRegionCallingFrom */
$metadataForRegionCallingFrom = $this->getMetadataForRegion($regionCallingFrom);
$internationalPrefix = $metadataForRegionCallingFrom->getInternationalPrefix();
// In general, if there is a preferred international prefix, use that. Otherwise, for regions
// that have multiple international prefixes, the international format of the number is
// returned since we would not know which one to use.
$internationalPrefixForFormatting = '';
if ($metadataForRegionCallingFrom->hasPreferredInternationalPrefix()) {
$internationalPrefixForFormatting = $metadataForRegionCallingFrom->getPreferredInternationalPrefix();
} else {
$uniqueInternationalPrefixMatcher = new Matcher(static::SINGLE_INTERNATIONAL_PREFIX, $internationalPrefix);
if ($uniqueInternationalPrefixMatcher->matches()) {
$internationalPrefixForFormatting = $internationalPrefix;
}
}
$regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
// Metadata cannot be null because the country calling code is valid.
/** @var PhoneMetadata $metadataForRegion */
$metadataForRegion = $this->getMetadataForRegionOrCallingCode($countryCallingCode, $regionCode);
$formattedNationalNumber = $this->formatNsn(
$nationalSignificantNumber,
$metadataForRegion,
PhoneNumberFormat::INTERNATIONAL
);
$formattedNumber = $formattedNationalNumber;
$this->maybeAppendFormattedExtension(
$number,
$metadataForRegion,
PhoneNumberFormat::INTERNATIONAL,
$formattedNumber
);
if ($internationalPrefixForFormatting !== '') {
$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).
* @return bool true if regionCode is one of the regions under NANPA
*/
public function isNANPACountry(string $regionCode): bool
{
return in_array(strtoupper($regionCode), $this->nanpaRegions, true);
}
/**
* Formats a phone number using the original phone number format (e.g. INTERNATIONAL or NATIONAL)
* that the number is parsed from, provided that the number has been parsed with
* parseAndKeepRawInput. Otherwise the number will be formatted in NATIONAL format.
*
* The original format is embedded in the country_code_source field of the PhoneNumber object
* passed in, which is only set when parsing keeps the raw input. When we don't have a formatting
* pattern for the number, the method falls back to returning the raw input.
*
* 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, string $regionCallingFrom): string
{
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 || $nationalPrefix === '') {
// 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 ($candidateNationalPrefixRule === '') {
// 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 = [];
$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 ($rawInput !== '') {
$normalizedFormattedNumber = static::normalizeDiallableCharsOnly($formattedNumber);
$normalizedRawInput = static::normalizeDiallableCharsOnly($rawInput);
if ($normalizedFormattedNumber !== $normalizedRawInput) {
$formattedNumber = $rawInput;
}
}
return $formattedNumber;
}
protected function hasFormattingPatternForNumber(PhoneNumber $number): bool
{
$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 bool $stripNonDigits true to strip non-digits from the national dialling prefix
* @return string|null the dialling prefix for the region denoted by regionCode
*/
public function getNddPrefixForRegion(string $regionCode, bool $stripNonDigits): ?string
{
$metadata = $this->getMetadataForRegion($regionCode);
if ($metadata === null) {
return null;
}
$nationalPrefix = $metadata->getNationalPrefix();
// If no national prefix was found, we return null.
if ($nationalPrefix === null || $nationalPrefix === '') {
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.
*/
protected function rawInputContainsNationalPrefix(string $rawInput, string $nationalPrefix, string $regionCode): bool
{
$normalizedNationalNumber = static::normalizeDigitsOnly($rawInput);
if (str_starts_with($normalizedNationalNumber, $nationalPrefix)) {
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) {
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 bool that indicates whether the number is of a valid pattern
*/
public function isValidNumber(PhoneNumber $number): bool
{
$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 {@see 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|null $regionCode the region that we want to validate the phone number for
* @return bool that indicates whether the number is of a valid pattern
*/
public function isValidNumberForRegion(PhoneNumber $number, ?string $regionCode): bool
{
$countryCode = $number->getCountryCode();
if ($countryCode === null) {
return false;
}
$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 {@see 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 {@see 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.
* @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(string $numberToParse, ?string $defaultRegion = null, ?PhoneNumber $phoneNumber = null, bool $keepRawInput = false): PhoneNumber
{
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 NumberFormat[] $userDefinedFormats formatting rules specified by clients
* @return string the formatted phone number
*/
public function formatByPattern(PhoneNumber $number, PhoneNumberFormat $numberFormat, array $userDefinedFormats): string
{
$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 ($nationalPrefixFormattingRule !== '') {
$nationalPrefix = $metadata->getNationalPrefix();
if ($nationalPrefix !== null && $nationalPrefix !== '') {
// Replace $NP with national prefix and $FG with the first group ($1).
$nationalPrefixFormattingRule = str_replace(
[static::NP_STRING, static::FG_STRING],
[$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 $regionCode string the region for which an example number is needed
* @return PhoneNumber|null 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 {@see getExampleNumberForNonGeoEntity} instead.
*/
public function getExampleNumber(string $regionCode): ?PhoneNumber
{
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(string $regionCode): ?PhoneNumber
{
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) {
// 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|PhoneNumberType $regionCodeOrType the region for which an example number is needed or the
* PhoneNumberType when not passing in $type
* @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
* {@see 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(string|PhoneNumberType $regionCodeOrType, ?PhoneNumberType $type = null): ?PhoneNumber
{
if ($type === null) {
if (!$regionCodeOrType instanceof PhoneNumberType) {
throw new TypeError('$regionCodeOrType must be a PhoneNumberType');
}
/*
* 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) {
// noop
}
}
// There are no example numbers of this type for any country in the library.
return null;
}
if (!is_string($regionCodeOrType)) {
throw new TypeError('$regionCodeOrType must be a string if $type is 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) {
// noop
}
return null;
}
protected function getNumberDescByType(PhoneMetadata $metadata, PhoneNumberType $type): PhoneNumberDesc
{
return match ($type) {
PhoneNumberType::PREMIUM_RATE => $metadata->getPremiumRate(),
PhoneNumberType::TOLL_FREE => $metadata->getTollFree(),
PhoneNumberType::MOBILE => $metadata->getMobile(),
PhoneNumberType::FIXED_LINE, PhoneNumberType::FIXED_LINE_OR_MOBILE => $metadata->getFixedLine(),
PhoneNumberType::SHARED_COST => $metadata->getSharedCost(),
PhoneNumberType::VOIP => $metadata->getVoip(),
PhoneNumberType::PERSONAL_NUMBER => $metadata->getPersonalNumber(),
PhoneNumberType::PAGER => $metadata->getPager(),
PhoneNumberType::UAN => $metadata->getUan(),
PhoneNumberType::VOICEMAIL => $metadata->getVoicemail(),
default => $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|null 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(int $countryCallingCode): ?PhoneNumber
{
$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 = [
$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) {
// 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 string|PhoneNumber 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 string|PhoneNumber 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
*/
public function isNumberMatch(PhoneNumber|string $firstNumberIn, PhoneNumber|string $secondNumberIn): MatchType
{
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) {
// Fall through and return MatchType::NOT_A_NUMBER
}
}
}
}
}
return MatchType::NOT_A_NUMBER;
}
if ($firstNumberIn instanceof PhoneNumber && is_string($secondNumberIn)) {
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) {
// 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.
*/
protected function isNationalNumberSuffixOfTheOther(PhoneNumber $firstNumber, PhoneNumber $secondNumber): bool
{
$firstNumberNationalNumber = trim((string) $firstNumber->getNationalNumber());
$secondNumberNationalNumber = trim((string) $secondNumber->getNationalNumber());
return str_ends_with($firstNumberNationalNumber, $secondNumberNationalNumber) || str_ends_with($secondNumberNationalNumber, $firstNumberNationalNumber);
}
/**
* 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.
*/
public function isMobileNumberPortableRegion(string $regionCode): bool
{
$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
* {@see isValidNumber}. See {@see isPossibleNumber(PhoneNumber)} for details.
*
* Convenience wrapper around {@see isPossibleNumberWithReason}. Instead of returning the reason
* for failure, this method returns a bool 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 string|PhoneNumber $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 bool true if the number is possible
*/
public function isPossibleNumber(PhoneNumber|string $number, ?string $regionDialingFrom = null): bool
{
if (is_string($number)) {
try {
return $this->isPossibleNumber($this->parse($number, $regionDialingFrom));
} catch (NumberParseException) {
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
* {@see isValidNumber} in the following sense:
*
* $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:
*
*
*
* @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.
*/
public function getLengthOfGeographicalAreaCode(PhoneNumber $number): int
{
$metadata = $this->getMetadataForRegion($this->getRegionCodeForNumber($number));
if ($metadata === null) {
return 0;
}
$countryCallingCode = $number->getCountryCode();
// If a country doesn't use a national prefix, and this number doesn't have an Italian leading
// zero, we assume it is a closed dialling plan with no area codes.
// Note:this is our general assumption, but there are exceptions which are tracked in
// COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES.
if (!$metadata->hasNationalPrefix()
&& !$number->isItalianLeadingZero()
&& !in_array($countryCallingCode, static::COUNTRIES_WITHOUT_NATIONAL_PREFIX_WITH_AREA_CODES, true)
) {
return 0;
}
$type = $this->getNumberType($number);
if ($type === PhoneNumberType::MOBILE
// Note this is a rough heuristic; it doesn't cover Indonesia well, for example, where area
// codes are present for some mobile phones but not for others. We have no better way of
// representing this in the metadata at this point.
&& in_array($countryCallingCode, static::GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES, true)
) {
return 0;
}
if (!$this->isNumberGeographical($type, $countryCallingCode)) {
return 0;
}
return $this->getLengthOfNationalDestinationCode($number);
}
/**
* Returns the metadata for the given region code or {@code null} if the region code is invalid
* or unknown.
*/
public function getMetadataForRegion(?string $regionCode): ?PhoneMetadata
{
if (!$this->isValidRegionCode($regionCode)) {
return null;
}
return $this->metadataSource->getMetadataForRegion($regionCode);
}
/**
* Helper function to check region code is not unknown or null.
*/
protected function isValidRegionCode(?string $regionCode): bool
{
return $regionCode !== null && in_array(strtoupper($regionCode), $this->supportedRegions, true);
}
/**
* Returns the region where a phone number is from. This could be used for geocoding at the region
* level. Only guarantees correct results for valid, full numbers (not short-codes, or invalid
* numbers).
*
* @param PhoneNumber $number the phone number whose origin we want to know
* @return null|string the region where the phone number is from, or null if no region matches this calling
* code
*/
public function getRegionCodeForNumber(PhoneNumber $number): ?string
{
$countryCode = $number->getCountryCode();
if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCode])) {
return null;
}
$regions = $this->countryCallingCodeToRegionCodeMap[$countryCode];
if (count($regions) === 1) {
return $regions[0];
}
return $this->getRegionCodeForNumberFromRegionList($number, $regions);
}
/**
* Returns the region code for a number from the list of region codes passing in.
* @param string[] $regionCodes
*/
protected function getRegionCodeForNumberFromRegionList(PhoneNumber $number, array $regionCodes): ?string
{
$nationalNumber = $this->getNationalSignificantNumber($number);
foreach ($regionCodes as $regionCode) {
// If leadingDigits is present, use this. Otherwise, do full validation.
// Metadata cannot be null because the region codes come from the country calling code map.
$metadata = $this->getMetadataForRegion($regionCode);
if ($metadata->hasLeadingDigits()) {
$nbMatches = preg_match(
'/' . $metadata->getLeadingDigits() . '/',
$nationalNumber,
$matches,
PREG_OFFSET_CAPTURE
);
if ($nbMatches > 0 && $matches[0][1] === 0) {
return $regionCode;
}
} elseif ($this->getNumberTypeHelper($nationalNumber, $metadata) !== PhoneNumberType::UNKNOWN) {
return $regionCode;
}
}
return null;
}
/**
* Gets the national significant number of the a phone number. Note a national significant number
* doesn't contain a national prefix or any formatting.
*
* @param PhoneNumber $number the phone number for which the national significant number is needed
* @return string the national significant number of the PhoneNumber object passed in
*/
public function getNationalSignificantNumber(PhoneNumber $number): string
{
// If leading zero(s) have been set, we prefix this now. Note this is not a national prefix.
$nationalNumber = '';
if ($number->isItalianLeadingZero() && $number->getNumberOfLeadingZeros() > 0) {
$zeros = str_repeat('0', $number->getNumberOfLeadingZeros());
$nationalNumber .= $zeros;
}
$nationalNumber .= $number->getNationalNumber();
return $nationalNumber;
}
protected function getNumberTypeHelper(string $nationalNumber, PhoneMetadata $metadata): PhoneNumberType
{
if (!$this->isNumberMatchingDesc($nationalNumber, $metadata->getGeneralDesc())) {
return PhoneNumberType::UNKNOWN;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPremiumRate())) {
return PhoneNumberType::PREMIUM_RATE;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getTollFree())) {
return PhoneNumberType::TOLL_FREE;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getSharedCost())) {
return PhoneNumberType::SHARED_COST;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoip())) {
return PhoneNumberType::VOIP;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPersonalNumber())) {
return PhoneNumberType::PERSONAL_NUMBER;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getPager())) {
return PhoneNumberType::PAGER;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getUan())) {
return PhoneNumberType::UAN;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getVoicemail())) {
return PhoneNumberType::VOICEMAIL;
}
$isFixedLine = $this->isNumberMatchingDesc($nationalNumber, $metadata->getFixedLine());
if ($isFixedLine) {
if ($metadata->getSameMobileAndFixedLinePattern()) {
return PhoneNumberType::FIXED_LINE_OR_MOBILE;
}
if ($this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())) {
return PhoneNumberType::FIXED_LINE_OR_MOBILE;
}
return PhoneNumberType::FIXED_LINE;
}
// Otherwise, test to see if the number is mobile. Only do this if certain that the patterns for
// mobile and fixed line aren't the same.
if (!$metadata->getSameMobileAndFixedLinePattern() &&
$this->isNumberMatchingDesc($nationalNumber, $metadata->getMobile())
) {
return PhoneNumberType::MOBILE;
}
return PhoneNumberType::UNKNOWN;
}
protected function isNumberMatchingDesc(string $nationalNumber, ?PhoneNumberDesc $numberDesc): bool
{
if ($numberDesc === null) {
return false;
}
// Check if any possible number lengths are present; if so, we use them to avoid checking the
// validation pattern if they don't match. If they are absent, this means they match the general
// description, which we have already checked before checking a specific number type.
$actualLength = mb_strlen($nationalNumber);
$possibleLengths = $numberDesc->getPossibleLength();
if (count($possibleLengths) > 0 && !in_array($actualLength, $possibleLengths, true)) {
return false;
}
return $this->matcherAPI->matchNationalNumber($nationalNumber, $numberDesc, false);
}
/**
* isNumberGeographical(PhoneNumber)
*
* Tests whether a phone number has a geographical association. It checks if the number is
* associated with a certain region in the country to which it belongs. Note that this doesn't
* verify if the number is actually in use.
*
* isNumberGeographical(PhoneNumberType, $countryCallingCode)
*
* Tests whether a phone number has a geographical association, as represented by its type and the
* country it belongs to.
*
* This version exists since calculating the phone number type is expensive; if we have already
* done this, we don't want to do it again.
*
* @param PhoneNumber|PhoneNumberType $phoneNumberObjOrType A PhoneNumber object, or a PhoneNumberType integer
* @param int|null $countryCallingCode Used when passing a PhoneNumberType
*/
public function isNumberGeographical(PhoneNumber|PhoneNumberType $phoneNumberObjOrType, ?int $countryCallingCode = null): bool
{
if ($phoneNumberObjOrType instanceof PhoneNumber) {
return $this->isNumberGeographical($this->getNumberType($phoneNumberObjOrType), $phoneNumberObjOrType->getCountryCode());
}
return $phoneNumberObjOrType === PhoneNumberType::FIXED_LINE
|| $phoneNumberObjOrType === PhoneNumberType::FIXED_LINE_OR_MOBILE
|| (in_array($countryCallingCode, static::GEO_MOBILE_COUNTRIES, true)
&& $phoneNumberObjOrType === PhoneNumberType::MOBILE);
}
/**
* Gets the type of a valid phone number.
*
* @param PhoneNumber $number the number the phone number that we want to know the type
* @return PhoneNumberType the type of the phone number, or PhoneNumberType::UNKNOWN if it is invalid
*/
public function getNumberType(PhoneNumber $number): PhoneNumberType
{
$regionCode = $this->getRegionCodeForNumber($number);
$metadata = $this->getMetadataForRegionOrCallingCode($number->getCountryCode(), $regionCode);
if ($metadata === null) {
return PhoneNumberType::UNKNOWN;
}
$nationalSignificantNumber = $this->getNationalSignificantNumber($number);
return $this->getNumberTypeHelper($nationalSignificantNumber, $metadata);
}
protected function getMetadataForRegionOrCallingCode(int $countryCallingCode, ?string $regionCode): ?PhoneMetadata
{
return static::REGION_CODE_FOR_NON_GEO_ENTITY === $regionCode ?
$this->getMetadataForNonGeographicalRegion($countryCallingCode) : $this->getMetadataForRegion($regionCode);
}
public function getMetadataForNonGeographicalRegion(int $countryCallingCode): ?PhoneMetadata
{
if (!isset($this->countryCallingCodeToRegionCodeMap[$countryCallingCode])) {
return null;
}
return $this->metadataSource->getMetadataForNonGeographicalRegion($countryCallingCode);
}
/**
* Gets the length of the national destination code (NDC) from the PhoneNumber object passed in,
* so that clients could use it to split a national significant number into NDC and subscriber
* number. The NDC of a phone number is normally the first group of digit(s) right after the
* country calling code when the number is formatted in the international format, if there is a
* subscriber number part that follows.
*
* follows.
*
* N.B.: similar to an area code, not all numbers have an NDC!
*
* An example of how this could be used:
*
*
* $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
* {@see 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): int
{
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 ($numberGroups === false || 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.
*/
public function format(PhoneNumber $number, PhoneNumberFormat $numberFormat): string
{
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 ($rawInput !== '') {
return $rawInput;
}
}
$formattedNumber = '';
$countryCallingCode = $number->getCountryCode();
$nationalSignificantNumber = $this->getNationalSignificantNumber($number);
if ($countryCallingCode === null) {
return $nationalSignificantNumber;
}
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.
*/
protected function prefixNumberWithCountryCallingCode(int $countryCallingCode, PhoneNumberFormat $numberFormat, string &$formattedNumber): void
{
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:
return;
}
}
/**
* Helper function to check the country calling code is valid.
*/
protected function hasValidCountryCallingCode(int $countryCallingCode): bool
{
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).
*/
public function getRegionCodeForCountryCode(int $countryCallingCode): string
{
$regionCodes = $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.
*/
protected function formatNsn(string $number, PhoneMetadata $metadata, PhoneNumberFormat $numberFormat, ?string $carrierCode = null): string
{
$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
*/
public function chooseFormattingPatternForNumber(array $availableFormats, string $nationalNumber): ?NumberFormat
{
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.
*/
public function formatNsnUsingPattern(
string $nationalNumber,
NumberFormat $formattingPattern,
PhoneNumberFormat $numberFormat,
?string $carrierCode = null,
): string {
$numberFormatRule = $formattingPattern->getFormat();
$m = new Matcher($formattingPattern->getPattern(), $nationalNumber);
if ($numberFormat === PhoneNumberFormat::NATIONAL &&
$carrierCode !== null && $carrierCode !== '' &&
$formattingPattern->getDomesticCarrierCodeFormattingRule() !== ''
) {
// 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 !== '') {
$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.
*/
protected function maybeAppendFormattedExtension(PhoneNumber $number, ?PhoneMetadata $metadata, PhoneNumberFormat $numberFormat, string &$formattedNumber): void
{
if ($number->hasExtension() && $number->getExtension() !== '') {
if ($numberFormat === PhoneNumberFormat::RFC3966) {
$formattedNumber .= static::RFC3966_EXTN_PREFIX . $number->getExtension();
} elseif ($metadata !== null && $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(int $countryCallingCode): string
{
return static::MOBILE_TOKEN_MAPPINGS[$countryCallingCode] ?? '';
}
/**
* 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 {@see isPossibleNumberWithReason} and
* {@see 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(string $number): bool
{
if (!static::isViablePhoneNumber($number)) {
// Number is too short, or doesn't match the basic phone number pattern.
return false;
}
$this->maybeStripExtension($number);
return preg_match('/' . static::VALID_ALPHA_PHONE_PATTERN . '/' . static::REGEX_FLAGS, $number) === 1;
}
/**
* 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 bool true if the number could be a phone number of some sort, otherwise false
*/
public static function isViablePhoneNumber(string $number): bool
{
if (!isset(static::$VALID_PHONE_NUMBER_PATTERN)) {
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.
*/
protected static function getValidPhoneNumberPattern(): string
{
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(string &$number): string
{
$matches = [];
$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 {@see 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|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 calling code for the number in this case would be stored
* as that of the default region supplied.
* @return PhoneNumber a phone number proto buffer filled with the parsed number
*/
public function parseAndKeepRawInput(string $numberToParse, ?string $defaultRegion, ?PhoneNumber $phoneNumber = null): PhoneNumber
{
if ($phoneNumber === null) {
$phoneNumber = new PhoneNumber();
}
$this->parseHelper($numberToParse, $defaultRegion, true, true, $phoneNumber);
return $phoneNumber;
}
/**
* A helper function to set the values related to leading zeros in a PhoneNumber.
*/
public static function setItalianLeadingZerosForPhoneNumber(string $nationalNumber, PhoneNumber $phoneNumber): void
{
if (strlen($nationalNumber) > 1 && str_starts_with($nationalNumber, '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) &&
$nationalNumber[$numberOfLeadingZeros] === '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").
* @throws NumberParseException
*/
protected function parseHelper(string $numberToParse, ?string $defaultRegion, bool $keepRawInput, bool $checkRegion, PhoneNumber $phoneNumber): void
{
$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 ($extension !== '') {
$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 && $carrierCode !== '') {
$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);
}
/**
* Extracts the value of the phone-context parameter of numberToExtractFrom where the index of
* ";phone-context=" is the parameter indexOfPhoneContext, following the syntax defined in
* RFC3966.
*
* @return string|null the extracted string (possibly empty), or null if no phone-context parameter is found.
*/
protected function extractPhoneContext(string $numberToExtractFrom, false|int $indexOfPhoneContext): ?string
{
// If no phone-context parameter is present
if ($indexOfPhoneContext === false) {
return null;
}
$phoneContextStart = $indexOfPhoneContext + strlen(static::RFC3966_PHONE_CONTEXT);
// If phone-context parameter is empty
if ($phoneContextStart >= mb_strlen($numberToExtractFrom)) {
return '';
}
$phoneContextEnd = strpos($numberToExtractFrom, ';', $phoneContextStart);
// If phone-context is not the last parameter
if ($phoneContextEnd !== false) {
return substr($numberToExtractFrom, $phoneContextStart, $phoneContextEnd - $phoneContextStart);
}
return substr($numberToExtractFrom, $phoneContextStart);
}
/**
* Returns whether the value of phoneContext follows the syntax defined in RFC3966.
*/
protected function isPhoneContextValid(?string $phoneContext): bool
{
if ($phoneContext === null) {
return true;
}
if ($phoneContext === '') {
return false;
}
$numberDigitsPattern = '/' . static::$RFC3966_GLOBAL_NUMBER_DIGITS . '/' . static::REGEX_FLAGS;
$domainNamePattern = '/' . static::$RFC3966_DOMAINNAME . '/' . static::REGEX_FLAGS;
// Does phone-context value match pattern of global-number-digits or domainname
return preg_match($numberDigitsPattern, $phoneContext) === 1 || preg_match($domainNamePattern, $phoneContext) === 1;
}
/**
* 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()
*/
protected static function copyCoreFieldsOnly(PhoneNumber $phoneNumberIn): PhoneNumber
{
$phoneNumber = new PhoneNumber();
$phoneNumber->setCountryCode($phoneNumberIn->getCountryCode());
$phoneNumber->setNationalNumber($phoneNumberIn->getNationalNumber());
if ($phoneNumberIn->hasExtension()) {
$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.
* @throws NumberParseException
*/
protected function buildNationalNumberForParsing(string $numberToParse, string &$nationalNumber): void
{
$indexOfPhoneContext = strpos($numberToParse, static::RFC3966_PHONE_CONTEXT);
$phoneContext = $this->extractPhoneContext($numberToParse, $indexOfPhoneContext);
if (!$this->isPhoneContextValid($phoneContext)) {
throw new NumberParseException(NumberParseException::NOT_A_NUMBER, 'The phone-context value is invalid.');
}
if ($phoneContext !== null) {
// If the phone context contains a phone number prefix, we need to capture it, whereas domains
// will be ignored.
if (str_starts_with($phoneContext, self::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.
$nationalNumber .= $phoneContext;
}
// 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,
(int) $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 string $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(string $number): string
{
$matches = [];
$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.
*/
protected function checkRegionForParsing(string $numberToParse, ?string $defaultRegion): bool
{
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 === '' || !$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:
*
*
* It will throw a NumberParseException if the number starts with a '+' but the country calling
* code supplied after this does not match that of any known region.
*
* @param string $number non-normalized telephone number that we wish to extract a country calling
* code from - may begin with '+'
* @param PhoneMetadata|null $defaultRegionMetadata metadata about the region this number may be from
* @param string $nationalNumber a string buffer to store the national significant number in, in the case
* that a country calling code was extracted. The number is appended to any existing contents.
* If no country calling code was extracted, this will be left unchanged.
* @param bool $keepRawInput true if the country_code_source and preferred_carrier_code fields of
* phoneNumber should be populated.
* @param PhoneNumber $phoneNumber the PhoneNumber object where the country_code and country_code_source need
* to be populated. Note the country_code is always populated, whereas country_code_source is
* only populated when keepCountryCodeSource is true.
* @return int the country calling code extracted or 0 if none could be extracted
* @throws NumberParseException
*/
public function maybeExtractCountryCode(
string $number,
?PhoneMetadata $defaultRegionMetadata,
string &$nationalNumber,
bool $keepRawInput,
PhoneNumber $phoneNumber
): int {
if ($number === '') {
return 0;
}
$fullNumber = $number;
// Set the default prefix to be something that will never match.
$possibleCountryIddPrefix = 'NonMatch';
if ($defaultRegionMetadata !== null) {
$possibleCountryIddPrefix = $defaultRegionMetadata->getInternationalPrefix();
}
$countryCodeSource = $this->maybeStripInternationalPrefixAndNormalize($fullNumber, $possibleCountryIddPrefix);
if ($keepRawInput) {
$phoneNumber->setCountryCodeSource($countryCodeSource);
}
if ($countryCodeSource !== CountryCodeSource::FROM_DEFAULT_COUNTRY) {
if (mb_strlen($fullNumber) <= static::MIN_LENGTH_FOR_NSN) {
throw new NumberParseException(
NumberParseException::TOO_SHORT_AFTER_IDD,
'Phone number had an IDD, but after this was not long enough to be a viable phone number.'
);
}
$potentialCountryCode = $this->extractCountryCode($fullNumber, $nationalNumber);
if ($potentialCountryCode !== 0) {
$phoneNumber->setCountryCode($potentialCountryCode);
return $potentialCountryCode;
}
// If this fails, they must be using a strange country calling code that we don't recognize,
// or that doesn't exist.
throw new NumberParseException(
NumberParseException::INVALID_COUNTRY_CODE,
'Country calling code supplied was not recognised.'
);
}
if ($defaultRegionMetadata !== null) {
// Check to see if the number starts with the country calling code for the default region. If
// so, we remove the country calling code, and do some checks on the validity of the number
// before and after.
$defaultCountryCode = $defaultRegionMetadata->getCountryCode();
$defaultCountryCodeString = (string) $defaultCountryCode;
$normalizedNumber = $fullNumber;
if (str_starts_with($normalizedNumber, $defaultCountryCodeString)) {
$potentialNationalNumber = substr($normalizedNumber, mb_strlen($defaultCountryCodeString));
$generalDesc = $defaultRegionMetadata->getGeneralDesc();
// Don't need the carrier code.
$carrierCode = '';
$this->maybeStripNationalPrefixAndCarrierCode(
$potentialNationalNumber,
$defaultRegionMetadata,
$carrierCode
);
// If the number was not valid before but is valid now, or if it was too long before, we
// consider the number with the country calling code stripped to be a better result and
// keep that instead.
if ((!$this->matcherAPI->matchNationalNumber($fullNumber, $generalDesc, false)
&& $this->matcherAPI->matchNationalNumber($potentialNationalNumber, $generalDesc, false))
|| $this->testNumberLength($fullNumber, $defaultRegionMetadata) === ValidationResult::TOO_LONG
) {
$nationalNumber .= $potentialNationalNumber;
if ($keepRawInput) {
$phoneNumber->setCountryCodeSource(CountryCodeSource::FROM_NUMBER_WITHOUT_PLUS_SIGN);
}
$phoneNumber->setCountryCode($defaultCountryCode);
return $defaultCountryCode;
}
}
}
// No country calling code present.
$phoneNumber->setCountryCode(0);
return 0;
}
/**
* Strips any international prefix (such as +, 00, 011) present in the number provided, normalizes
* the resulting number, and indicates if an international prefix was present.
*
* @param string $number the non-normalized telephone number that we wish to strip any international
* dialing prefix from.
* @param string $possibleIddPrefix string the international direct dialing prefix from the region we
* think this number may be dialed in
* @return CountryCodeSource the corresponding CountryCodeSource if an international dialing prefix could be
* removed from the number, otherwise CountryCodeSource::FROM_DEFAULT_COUNTRY if the number did
* not seem to be in international format.
*/
public function maybeStripInternationalPrefixAndNormalize(string &$number, string $possibleIddPrefix): CountryCodeSource
{
if ($number === '') {
return CountryCodeSource::FROM_DEFAULT_COUNTRY;
}
$matches = [];
// Check to see if the number begins with one or more plus signs.
$match = preg_match('/^' . static::PLUS_CHARS_PATTERN . '/' . static::REGEX_FLAGS, $number, $matches, PREG_OFFSET_CAPTURE);
if ($match > 0) {
$number = mb_substr($number, $matches[0][1] + mb_strlen($matches[0][0]));
// Can now normalize the rest of the number since we've consumed the "+" sign at the start.
$number = static::normalize($number);
return CountryCodeSource::FROM_NUMBER_WITH_PLUS_SIGN;
}
// Attempt to parse the first digits as an international prefix.
$iddPattern = $possibleIddPrefix;
$number = static::normalize($number);
return $this->parsePrefixAsIdd($iddPattern, $number)
? CountryCodeSource::FROM_NUMBER_WITH_IDD
: CountryCodeSource::FROM_DEFAULT_COUNTRY;
}
/**
* Normalizes a string of characters representing a phone number. This performs
* the following conversions:
* Punctuation is stripped.
* For ALPHA/VANITY numbers:
* Letters are converted to their numeric representation on a telephone
* keypad. The keypad used here is the one defined in ITU Recommendation
* E.161. This is only done if there are 3 or more letters in the number,
* to lessen the risk that such letters are typos.
* For other numbers:
* - Wide-ascii digits are converted to normal ASCII (European) digits.
* - Arabic-Indic numerals are converted to European numerals.
* - Spurious alpha characters are stripped.
*
* @param string $number a string of characters representing a phone number.
* @return string the normalized string version of the phone number.
*/
public static function normalize(string $number): string
{
$m = new Matcher(static::VALID_ALPHA_PHONE_PATTERN, $number);
if ($m->matches()) {
return static::normalizeHelper($number, static::ALPHA_PHONE_MAPPINGS, true);
}
return static::normalizeDigitsOnly($number);
}
/**
* Normalizes a string of characters representing a phone number. This converts wide-ascii and
* arabic-indic numerals to European numerals, and strips punctuation and alpha characters.
*
* @param $number string a string of characters representing a phone number
* @return string the normalized string version of the phone number
*/
public static function normalizeDigitsOnly(string $number): string
{
return static::normalizeDigits($number, false /* strip non-digits */);
}
public static function normalizeDigits(string $number, bool $keepNonDigits): string
{
$normalizedDigits = '';
$numberAsArray = preg_split('/(?lookingAt()) {
$matchEnd = $m->end();
// Only strip this if the first digit after the match is not a 0, since country calling codes
// cannot begin with 0.
$digitMatcher = new Matcher(static::CAPTURING_DIGIT_PATTERN, substr($number, $matchEnd));
if ($digitMatcher->find()) {
$normalizedGroup = static::normalizeDigitsOnly($digitMatcher->group(1));
if ($normalizedGroup === '0') {
return false;
}
}
$number = substr($number, $matchEnd);
return true;
}
return false;
}
/**
* Extracts country calling code from fullNumber, returns it and places the remaining number in nationalNumber.
* It assumes that the leading plus sign or IDD has already been removed.
* Returns 0 if fullNumber doesn't start with a valid country calling code, and leaves nationalNumber unmodified.
* @internal
*/
public function extractCountryCode(string $fullNumber, string &$nationalNumber): int
{
if (($fullNumber === '') || ($fullNumber[0] === '0')) {
// Country codes do not begin with a '0'.
return 0;
}
$numberLength = mb_strlen($fullNumber);
for ($i = 1; $i <= static::MAX_LENGTH_COUNTRY_CODE && $i <= $numberLength; $i++) {
$potentialCountryCode = (int) substr($fullNumber, 0, $i);
if (isset($this->countryCallingCodeToRegionCodeMap[$potentialCountryCode])) {
$nationalNumber .= substr($fullNumber, $i);
return $potentialCountryCode;
}
}
return 0;
}
/**
* Strips any national prefix (such as 0, 1) present in the number provided.
*
* @param string $number the normalized telephone number that we wish to strip any national
* dialing prefix from
* @param PhoneMetadata $metadata the metadata for the region that we think this number is from
* @param string $carrierCode a place to insert the carrier code if one is extracted
* @return bool true if a national prefix or carrier code (or both) could be extracted.
*/
public function maybeStripNationalPrefixAndCarrierCode(string &$number, PhoneMetadata $metadata, string &$carrierCode): bool
{
$possibleNationalPrefix = $metadata->getNationalPrefixForParsing();
if ($number === '' || $possibleNationalPrefix === null || $possibleNationalPrefix === '') {
// Early return for numbers of zero length.
return false;
}
// Attempt to parse the first digits as a national prefix.
$prefixMatcher = new Matcher($possibleNationalPrefix, $number);
if ($prefixMatcher->lookingAt()) {
$generalDesc = $metadata->getGeneralDesc();
// Check if the original number is viable.
$isViableOriginalNumber = $this->matcherAPI->matchNationalNumber($number, $generalDesc, false);
// $prefixMatcher->group($numOfGroups) === null implies nothing was captured by the capturing
// groups in $possibleNationalPrefix; therefore, no transformation is necessary, and we just
// remove the national prefix
$numOfGroups = $prefixMatcher->groupCount();
$transformRule = $metadata->getNationalPrefixTransformRule();
if ($transformRule === null
|| $transformRule === ''
|| $prefixMatcher->group($numOfGroups - 1) === null
) {
// If the original number was viable, and the resultant number is not, we return.
if ($isViableOriginalNumber &&
!$this->matcherAPI->matchNationalNumber(
substr($number, $prefixMatcher->end()),
$generalDesc,
false
)) {
return false;
}
if ($numOfGroups > 0 && $prefixMatcher->group($numOfGroups) !== null) {
$carrierCode .= $prefixMatcher->group(1);
}
$number = substr($number, $prefixMatcher->end());
return true;
}
// Check that the resultant number is still viable. If not, return. Check this by copying
// the string and making the transformation on the copy first.
$transformedNumber = $number;
$numberLength = mb_strlen($number);
$transformedNumber = substr_replace(
$transformedNumber,
$prefixMatcher->replaceFirst($transformRule),
0,
$numberLength
);
if ($isViableOriginalNumber
&& !$this->matcherAPI->matchNationalNumber($transformedNumber, $generalDesc, false)) {
return false;
}
if ($numOfGroups > 1) {
$carrierCode .= $prefixMatcher->group(1);
}
$number = substr_replace($number, $transformedNumber, 0, mb_strlen($number));
return true;
}
return false;
}
/**
* Convenience wrapper around isPossibleNumberForTypeWithReason. Instead of returning the reason
* 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.
*
* @param PhoneNumber $number The number that needs to be checked
* @param PhoneNumberType $type PhoneNumberType The type we are interested in
* @return bool true if the number is possible for this particular type
*/
public function isPossibleNumberForType(PhoneNumber $number, PhoneNumberType $type): bool
{
$result = $this->isPossibleNumberForTypeWithReason($number, $type);
return $result === ValidationResult::IS_POSSIBLE
|| $result === ValidationResult::IS_POSSIBLE_LOCAL_ONLY;
}
/**
* Helper method to check a number against possible lengths for this number type, and determine
* whether it matches, or is too short or too long.
*/
protected function testNumberLength(string $number, PhoneMetadata $metadata, PhoneNumberType $type = PhoneNumberType::UNKNOWN): ValidationResult
{
$descForType = $this->getNumberDescByType($metadata, $type);
// There should always be "possibleLengths" set for every element. This is declared in the XML
// schema which is verified by PhoneNumberMetadataSchemaTest.
// For size efficiency, where a sub-description (e.g. fixed-line) has the same possibleLengths
// as the parent, this is missing, so we fall back to the general desc (where no numbers of the
// type exist at all, there is one possible length (-1) which is guaranteed not to match the
// length of any real phone number).
$possibleLengths = (count($descForType->getPossibleLength()) === 0)
? $metadata->getGeneralDesc()->getPossibleLength() : $descForType->getPossibleLength();
$localLengths = $descForType->getPossibleLengthLocalOnly();
if ($type === PhoneNumberType::FIXED_LINE_OR_MOBILE) {
if (!static::descHasPossibleNumberData($this->getNumberDescByType($metadata, PhoneNumberType::FIXED_LINE))) {
// The rate case has been encountered where no fixedLine data is available (true for some
// non-geographical entities), so we just check mobile.
return $this->testNumberLength($number, $metadata, PhoneNumberType::MOBILE);
}
$mobileDesc = $this->getNumberDescByType($metadata, PhoneNumberType::MOBILE);
if (static::descHasPossibleNumberData($mobileDesc)) {
// Note that when adding the possible lengths from mobile, we have to again check they
// aren't empty since if they are this indicates they are the same as the general desc and
// should be obtained from there.
$possibleLengths = array_merge(
$possibleLengths,
(count($mobileDesc->getPossibleLength()) === 0)
? $metadata->getGeneralDesc()->getPossibleLength() : $mobileDesc->getPossibleLength()
);
// The current list is sorted; we need to merge in the new list and re-sort (duplicates
// are okay). Sorting isn't so expensive because the lists are very small.
sort($possibleLengths);
if (count($localLengths) === 0) {
$localLengths = $mobileDesc->getPossibleLengthLocalOnly();
} else {
$localLengths = array_merge($localLengths, $mobileDesc->getPossibleLengthLocalOnly());
sort($localLengths);
}
}
}
// If the type is not supported at all (indicated by the possible lengths containing -1 at this
// point) we return invalid length.
if ($possibleLengths[0] === -1) {
return ValidationResult::INVALID_LENGTH;
}
$actualLength = mb_strlen($number);
// This is safe because there is never an overlap between the possible lengths and the local-only
// lengths; this is checked at build time.
if (in_array($actualLength, $localLengths, true)) {
return ValidationResult::IS_POSSIBLE_LOCAL_ONLY;
}
$minimumLength = reset($possibleLengths);
if ($minimumLength === $actualLength) {
return ValidationResult::IS_POSSIBLE;
}
if ($minimumLength > $actualLength) {
return ValidationResult::TOO_SHORT;
}
if (isset($possibleLengths[count($possibleLengths) - 1]) && $possibleLengths[count($possibleLengths) - 1] < $actualLength) {
return ValidationResult::TOO_LONG;
}
// We skip the first element; we've already checked it.
array_shift($possibleLengths);
return in_array($actualLength, $possibleLengths, true) ? ValidationResult::IS_POSSIBLE : ValidationResult::INVALID_LENGTH;
}
/**
* Returns a list with the region codes that match the specific country calling code. For
* non-geographical country calling codes, the region code 001 is returned. Also, in the case
* of no region code being found, an empty list is returned.
* @return string[]
*/
public function getRegionCodesForCountryCode(int $countryCallingCode): array
{
$regionCodes = $this->countryCallingCodeToRegionCodeMap[$countryCallingCode] ?? null;
return $regionCodes ?? [];
}
/**
* Returns the country calling code for a specific region. For example, this would be 1 for the
* United States, and 64 for New Zealand. Assumes the region is already valid.
*
* @param string $regionCode the region that we want to get the country calling code for
* @return int the country calling code for the region denoted by regionCode
*/
public function getCountryCodeForRegion(string $regionCode): int
{
if (!$this->isValidRegionCode($regionCode)) {
return 0;
}
return $this->getCountryCodeForValidRegion($regionCode);
}
/**
* Returns the country calling code for a specific region. For example, this would be 1 for the
* United States, and 64 for New Zealand. Assumes the region is already valid.
*
* @param string $regionCode the region that we want to get the country calling code for
* @return int the country calling code for the region denoted by regionCode
* @throws InvalidArgumentException if the region is invalid
*/
protected function getCountryCodeForValidRegion(string $regionCode): int
{
$metadata = $this->getMetadataForRegion($regionCode);
if ($metadata === null) {
throw new InvalidArgumentException('Invalid region code: ' . $regionCode);
}
return $metadata->getCountryCode();
}
/**
* Returns a number formatted in such a way that it can be dialed from a mobile phone in a
* specific region. If the number cannot be reached from the region (e.g. some countries block
* toll-free numbers from being called outside of the country), the method returns an empty
* string.
*
* @param PhoneNumber $number the phone number to be formatted
* @param string $regionCallingFrom the region where the call is being placed
* @param bool $withFormatting whether the number should be returned with formatting symbols, such as
* spaces and dashes.
* @return string the formatted phone number
*/
public function formatNumberForMobileDialing(PhoneNumber $number, string $regionCallingFrom, bool $withFormatting): string
{
$countryCallingCode = $number->getCountryCode();
if (!$this->hasValidCountryCallingCode($countryCallingCode)) {
return $number->hasRawInput() ? $number->getRawInput() : '';
}
$formattedNumber = '';
// Clear the extension, as that part cannot normally be dialed together with the main number.
$numberNoExt = new PhoneNumber();
$numberNoExt->mergeFrom($number)->clearExtension();
$regionCode = $this->getRegionCodeForCountryCode($countryCallingCode);
$numberType = $this->getNumberType($numberNoExt);
$isValidNumber = ($numberType !== PhoneNumberType::UNKNOWN);
if (strtoupper($regionCallingFrom) === $regionCode) {
$isFixedLineOrMobile = ($numberType === PhoneNumberType::FIXED_LINE || $numberType === PhoneNumberType::MOBILE || $numberType === PhoneNumberType::FIXED_LINE_OR_MOBILE);
// Carrier codes may be needed in some countries. We handle this here.
if ($regionCode === 'BR' && $isFixedLineOrMobile) {
// 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.
$formattedNumber = $numberNoExt->getPreferredDomesticCarrierCode() !== ''
? $this->formatNationalNumberWithPreferredCarrierCode($numberNoExt, '')
// Brazilian fixed line and mobile numbers need to be dialed with a carrier code when
// called within Brazil. Without that, most of the carriers won't connect the call.
// Because of that, we return an empty string here.
: '';
} elseif ($countryCallingCode === static::NANPA_COUNTRY_CODE) {
// For NANPA countries, we output international format for numbers that can be dialed
// internationally, since that always works, except for numbers which might potentially be
// short numbers, which are always dialled in national format.
$regionMetadata = $this->getMetadataForRegion($regionCallingFrom);
if ($this->canBeInternationallyDialled($numberNoExt)
&& $this->testNumberLength($this->getNationalSignificantNumber($numberNoExt), $regionMetadata)
!== ValidationResult::TOO_SHORT
) {
$formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL);
} else {
$formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::NATIONAL);
}
} elseif ((
$regionCode === static::REGION_CODE_FOR_NON_GEO_ENTITY ||
// MX fixed line and mobile numbers should always be formatted in international format,
// even when dialed within MX. For national format to work, a carrier code needs to be
// used, and the correct carrier code depends on if the caller and callee are from the
// same local area. It is trickier to get that to work correctly than using
// international format, which is tested to work fine on all carriers.
// CL fixed line numbers need the national prefix when dialing in the national format,
// but don't have it when used for display. The reverse is true for mobile numbers.
// As a result, we output them in the international format to make it work.
(
($regionCode === 'MX' || $regionCode === 'CL' || $regionCode === 'UZ')
&& $isFixedLineOrMobile
)
) && $this->canBeInternationallyDialled($numberNoExt)
) {
$formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL);
} else {
$formattedNumber = $this->format($numberNoExt, PhoneNumberFormat::NATIONAL);
}
} elseif ($isValidNumber && $this->canBeInternationallyDialled($numberNoExt)) {
// We assume that short numbers are not diallable from outside their region, so if a number
// is not a valid regular length phone number, we treat it as if it cannot be internationally
// dialled.
return $withFormatting ?
$this->format($numberNoExt, PhoneNumberFormat::INTERNATIONAL) :
$this->format($numberNoExt, PhoneNumberFormat::E164);
}
return $withFormatting ? $formattedNumber : static::normalizeDiallableCharsOnly($formattedNumber);
}
/**
* Formats a phone number in national format for dialing using the carrier as specified in the
* {@code carrierCode}. The {@code carrierCode} will always be used regardless of whether the
* phone number already has a preferred domestic carrier code stored. If {@code carrierCode}
* contains an empty string, returns the number in national format without any carrier code.
*
* @param PhoneNumber $number the phone number to be formatted
* @param string|null $carrierCode the carrier selection code to be used
* @return string the formatted phone number in national format for dialing using the carrier as
* specified in the {@code carrierCode}
*/
public function formatNationalNumberWithCarrierCode(PhoneNumber $number, ?string $carrierCode): string
{
$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 = $this->formatNsn(
$nationalSignificantNumber,
$metadata,
PhoneNumberFormat::NATIONAL,
$carrierCode
);
$this->maybeAppendFormattedExtension($number, $metadata, PhoneNumberFormat::NATIONAL, $formattedNumber);
$this->prefixNumberWithCountryCallingCode(
$countryCallingCode,
PhoneNumberFormat::NATIONAL,
$formattedNumber
);
return $formattedNumber;
}
/**
* Formats a phone number in national format for dialing using the carrier as specified in the
* preferredDomesticCarrierCode field of the PhoneNumber object passed in. If that is missing,
* use the {@code fallbackCarrierCode} passed in instead. If there is no
* {@code preferredDomesticCarrierCode}, and the {@code fallbackCarrierCode} contains an empty
* string, return the number in national format without any carrier code.
*
*
*
*
* @param PhoneNumber $number the phone number that needs to be formatted
* @param $regionCallingFrom string the region where the call is being placed
* @return string the formatted phone number
*/
public function formatOutOfCountryKeepingAlphaChars(PhoneNumber $number, string $regionCallingFrom): string
{
$rawInput = $number->getRawInput();
// If there is no raw input, then we can't keep alpha characters because there aren't any.
// In this case, we return formatOutOfCountryCallingNumber.
if ($rawInput === null || $rawInput === '') {
return $this->formatOutOfCountryCallingNumber($number, $regionCallingFrom);
}
$countryCode = $number->getCountryCode();
if (!$this->hasValidCountryCallingCode($countryCode)) {
return $rawInput;
}
// Strip any prefix such as country calling code, IDD, that was present. We do this by comparing
// the number in raw_input with the parsed number.
// To do this, first we normalize punctuation. We retain number grouping symbols such as " "
// only.
$rawInput = self::normalizeHelper($rawInput, static::$ALL_PLUS_NUMBER_GROUPING_SYMBOLS, true);
// Now we trim everything before the first three digits in the parsed number. We choose three
// because all valid alpha numbers have 3 digits at the start - if it does not, then we don't
// trim anything at all. Similarly, if the national number was less than three digits, we don't
// trim anything at all.
$nationalNumber = $this->getNationalSignificantNumber($number);
if (mb_strlen($nationalNumber) > 3) {
$firstNationalNumberDigit = strpos($rawInput, substr($nationalNumber, 0, 3));
if ($firstNationalNumberDigit !== false) {
$rawInput = substr($rawInput, $firstNationalNumberDigit);
}
}
$metadataForRegionCallingFrom = $this->getMetadataForRegion($regionCallingFrom);
if ($countryCode === static::NANPA_COUNTRY_CODE) {
if ($this->isNANPACountry($regionCallingFrom)) {
return $countryCode . ' ' . $rawInput;
}
} elseif ($metadataForRegionCallingFrom !== null &&
$countryCode === $this->getCountryCodeForValidRegion($regionCallingFrom)
) {
$formattingPattern =
$this->chooseFormattingPatternForNumber(
$metadataForRegionCallingFrom->numberFormats(),
$nationalNumber
);
if ($formattingPattern === null) {
// If no pattern above is matched, we format the original input.
return $rawInput;
}
$newFormat = new NumberFormat();
$newFormat->mergeFrom($formattingPattern);
// The first group is the first group of digits that the user wrote together.
$newFormat->setPattern('(\\d+)(.*)');
// Here we just concatenate them back together after the national prefix has been fixed.
$newFormat->setFormat('$1$2');
// Now we format using this pattern instead of the default pattern, but with the national
// prefix prefixed if necessary.
// This will not work in the cases where the pattern (and not the leading digits) decide
// whether a national prefix needs to be used, since we have overridden the pattern to match
// anything, but that is not the case in the metadata to date.
return $this->formatNsnUsingPattern($rawInput, $newFormat, PhoneNumberFormat::NATIONAL);
}
$internationalPrefixForFormatting = '';
// If an unsupported region-calling-from is entered, or a country with multiple international
// prefixes, the international format of the number is returned, unless there is a preferred
// international prefix.
if ($metadataForRegionCallingFrom !== null) {
$internationalPrefix = $metadataForRegionCallingFrom->getInternationalPrefix();
$uniqueInternationalPrefixMatcher = new Matcher(static::SINGLE_INTERNATIONAL_PREFIX, $internationalPrefix);
$internationalPrefixForFormatting =
$uniqueInternationalPrefixMatcher->matches()
? $internationalPrefix
: $metadataForRegionCallingFrom->getPreferredInternationalPrefix();
}
$formattedNumber = $rawInput;
$regionCode = $this->getRegionCodeForCountryCode($countryCode);
// Metadata cannot be null because the country calling code is valid.
$metadataForRegion = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
// Strip any extension
$this->maybeStripExtension($formattedNumber);
// Append the formatted extension
$this->maybeAppendFormattedExtension(
$number,
$metadataForRegion,
PhoneNumberFormat::INTERNATIONAL,
$formattedNumber
);
if ($internationalPrefixForFormatting !== null && $internationalPrefixForFormatting !== '') {
$formattedNumber = $internationalPrefixForFormatting . ' ' . $countryCode . ' ' . $formattedNumber;
} else {
// Invalid region entered as country-calling-from (so no metadata was found for it) or the
// region chosen has multiple international dialling prefixes.
$this->prefixNumberWithCountryCallingCode(
$countryCode,
PhoneNumberFormat::INTERNATIONAL,
$formattedNumber
);
}
return $formattedNumber;
}
/**
* Formats a phone number for out-of-country dialing purposes. If no regionCallingFrom is
* supplied, we format the number in its INTERNATIONAL format. If the country calling code is the
* same as that of the region where the number is from, then NATIONAL formatting will be applied.
*
*
*
*
* There is a known issue with this
* method: if a number is possible only in a certain region among several regions that share the
* same country calling code, this method will consider only the "main" region. For example,
* +1310xxxx are valid numbers in Canada. However, they are not possible in the US. As a result,
* this method will return IS_POSSIBLE_LOCAL_ONLY for +1310xxxx.
*
* @param PhoneNumber $number the number that needs to be checked
* @return ValidationResult object which indicates whether the number is possible
*/
public function isPossibleNumberWithReason(PhoneNumber $number): ValidationResult
{
return $this->isPossibleNumberForTypeWithReason($number, PhoneNumberType::UNKNOWN);
}
/**
* Check whether a phone number is a possible number of a particular type. For types that don't
* exist in a particular region, this will return a result that isn't so useful; it is recommended
* that you use {@see getSupportedTypesForRegion} or {@see getSupportedTypesForNonGeoEntity}
* respectively before calling this method to determine whether you should call it for this number
* at all.
*
* This provides a more lenient check than {@see isValidNumber} in the following sense:
*
*
*
*
* There is a known issue with this
* method: if a number is possible only in a certain region among several regions that share the
* same country calling code, this method will consider only the "main" region. For example,
* +1310xxxx are valid numbers in Canada. However, they are not possible in the US. As a result,
* this method will return IS_POSSIBLE_LOCAL_ONLY for +1310xxxx.
*
* @param PhoneNumber $number the number that needs to be checked
* @param PhoneNumberType $type the PhoneNumberType we are interested in
* @return ValidationResult object which indicates whether the number is possible
*/
public function isPossibleNumberForTypeWithReason(PhoneNumber $number, PhoneNumberType $type): ValidationResult
{
$nationalNumber = $this->getNationalSignificantNumber($number);
$countryCode = $number->getCountryCode();
// Note: For regions that share a country calling code, like NANPA numbers, we just use the
// rules from the default region (US in this case) since the getRegionCodeForNumber will not
// work if the number is possible but not valid. There is in fact one country calling code (290)
// where the possible number pattern differs between various regions (Saint Helena and Tristan
// da Cuñha), but this is handled by putting all possible lengths for any country with this
// country calling code in the metadata for the default region in this case.
if (!$this->hasValidCountryCallingCode($countryCode)) {
return ValidationResult::INVALID_COUNTRY_CODE;
}
$regionCode = $this->getRegionCodeForCountryCode($countryCode);
// Metadata cannot be null because the country calling code is valid.
$metadata = $this->getMetadataForRegionOrCallingCode($countryCode, $regionCode);
return $this->testNumberLength($nationalNumber, $metadata, $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 bool true if a valid phone number can be successfully extracted.
*/
public function truncateTooLongNumber(PhoneNumber $number): bool
{
if ($this->isValidNumber($number)) {
return true;
}
$numberCopy = new PhoneNumber();
$numberCopy->mergeFrom($number);
$nationalNumber = $number->getNationalNumber();
do {
$nationalNumber = (string) floor((int) $nationalNumber / 10);
$numberCopy->setNationalNumber($nationalNumber);
if ($nationalNumber === '0' || $this->isPossibleNumberWithReason($numberCopy) === ValidationResult::TOO_SHORT) {
return false;
}
} while (!$this->isValidNumber($numberCopy));
$number->setNationalNumber($nationalNumber);
return true;
}
}