If you use this library, and want to be notified about important changes, please sign up to our mailing list. NOTE: A lot of methods in this class require Region Code strings. These must be provided using ISO 3166-1 two-letter country-code format. These should be in upper-case. The list of the codes can be found here: http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm
Mostrar archivo Open project: giggsey/libphonenumber-for-php Class Usage ExamplesProperty | Type | Description | |
---|---|---|---|
$PLUS_CHARS_PATTERN |
Property | Type | Description | |
---|---|---|---|
$ALL_PLUS_NUMBER_GROUPING_SYMBOLS | array | Separate map of all symbols that we wish to retain when formatting alpha numbers. This includes digits, ASCII letters and number grouping symbols such as "-" and " ". | |
$ALPHA_MAPPINGS | array | Only upper-case variants of alpha characters are stored. | |
$ALPHA_PHONE_MAPPINGS | array | For performance reasons, amalgamate both into one map. | |
$CAPTURING_DIGIT_PATTERN | |||
$CAPTURING_EXTN_DIGITS | |||
$DIALLABLE_CHAR_MAPPINGS | |||
$EXTN_PATTERN | |||
$EXTN_PATTERNS_FOR_PARSING | String | Regexp of all possible ways to write extensions, for use when parsing. This will be run as a case-insensitive regexp match. Wide character versions are also provided after each ASCII version. | |
$GEO_MOBILE_COUNTRIES | array | Set of country calling codes that have geographically assigned mobile numbers. This may not be complete; we add calling codes case by case, as we find geographical mobile numbers or hear from user reports. Note that countries like the US, where we can't distinguish between fixed-line or mobile numbers, are not listed here, since we consider FIXED_LINE_OR_MOBILE to be a possibly geographically-related type anyway (like FIXED_LINE). | |
$GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES | array | Set of country codes that have geographically assigned mobile numbers (see GEO_MOBILE_COUNTRIES below) which are not based on *area codes*. For example, in China mobile numbers start with a carrier indicator, and beyond that are geographically assigned: this carrier indicator is not considered to be an area code. | |
$MIN_LENGTH_PHONE_NUMBER_PATTERN | |||
$MOBILE_TOKEN_MAPPINGS | array | Map of country calling codes that use a mobile token before the area code. One example of when this is relevant is when determining the length of the national destination code, which should be the length of the area code plus the length of the mobile token. | |
$SECOND_NUMBER_START_PATTERN | |||
$SEPARATOR_PATTERN | |||
$UNWANTED_END_CHAR_PATTERN | |||
$VALID_PHONE_NUMBER | string | The symbol 'x' is allowed here as valid punctuation since it is often used as a placeholder for carrier codes, for example in Brazilian phone numbers. We also allow multiple "+" characters at the start. Corresponds to the following: [digits]{minLengthNsn}| plus_sign*(([punctuation]|[star])*[digits]){3,}([punctuation]|[star]|[digits]|[alpha])* The first reg-ex is to allow short numbers (two digits long) to be parsed if they are entered as "15" etc, but only if there is no punctuation in them. The second expression restricts the number of digits to three or more, but then allows them to be in international form, and to have alpha-characters and punctuation. Note VALID_PUNCTUATION starts with a -, so must be the first in the range. | |
$VALID_PHONE_NUMBER_PATTERN | |||
$VALID_START_CHAR_PATTERN | |||
$asciiDigitMappings | array | Simple ASCII digits map used to populate ALPHA_PHONE_MAPPINGS and ALL_PLUS_NUMBER_GROUPING_SYMBOLS. | |
$countryCallingCodeToRegionCodeMap | array | A mapping from a country calling code to the region codes which denote the region represented by that country calling code. In the case of multiple regions sharing a calling code, such as the NANPA regions, the one indicated with "isMainCountryForCode" in the metadata should be first. | |
$countryCodesForNonGeographicalRegion | array | The set of county calling codes that map to the non-geo entity region ("001"). | |
$instance | |||
$metadataSource | libphonenumber\MetadataSourceInterface | ||
$nanpaRegions | array | The set of regions that share country calling code 1. | |
$numericCharacters | |||
$supportedRegions | array | The set of regions the library supports. |
Method | Description | |
---|---|---|
canBeInternationallyDialled ( |
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. | |
chooseFormattingPatternForNumber ( array $availableFormats, string $nationalNumber ) : |
||
convertAlphaCharactersInNumber ( string $number ) : string | Converts all alpha characters in a number to their respective digits on a keypad, but retains existing formatting. | |
extractPossibleNumber ( integer $number ) : string | 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. | |
format ( |
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. | |
formatByPattern ( |
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. | |
formatInOriginalFormat ( |
Formats a phone number using the original phone number format that the number is parsed from. | |
formatNationalNumberWithCarrierCode ( |
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. | |
formatNationalNumberWithPreferredCarrierCode ( |
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. | |
formatNumberForMobileDialing ( |
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. | |
formatOutOfCountryCallingNumber ( |
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. | |
formatOutOfCountryKeepingAlphaChars ( |
Formats a phone number for out-of-country dialing purposes. | |
formattingRuleHasFirstGroupOnly ( string $nationalPrefixFormattingRule ) : boolean | Helper function to check if the national prefix formatting rule has the first group only, i.e., does not start with the national prefix. | |
getCountryCodeForRegion ( string $regionCode ) : integer | 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. | |
getCountryMobileToken ( integer $countryCallingCode ) : string | 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. | |
getExampleNumber ( $regionCode ) : |
Gets a valid number for the specified region. | |
getExampleNumberForNonGeoEntity ( integer $countryCallingCode ) : |
Gets a valid number for the specified country calling code for a non-geographical entity. | |
getExampleNumberForType ( string | integer $regionCodeOrType, integer $type = null ) : |
Gets a valid number for the specified region and number type. | |
getInstance ( string $baseFileLocation = self::META_DATA_FILE_PREFIX, array $countryCallingCodeToRegionCodeMap = null, libphonenumber\MetadataLoaderInterface $metadataLoader = null, libphonenumber\MetadataSourceInterface $metadataSource = null ) : |
Gets a {@link PhoneNumberUtil} instance to carry out international phone number formatting, parsing, or validation. The instance is loaded with phone number metadata for a number of most commonly used regions. | |
getInvalidExampleNumber ( string $regionCode ) : |
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}. | |
getLengthOfGeographicalAreaCode ( |
Gets the length of the geographical area code from the {@code nationalNumber} field of the PhoneNumber object passed in, so that clients could use it to split a national significant number into geographical area code and subscriber number. It works in such a way that the resultant subscriber number should be diallable, at least on some devices. An example of how this could be used: | |
getLengthOfNationalDestinationCode ( |
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. An example of how this could be used: | |
getMetadataForNonGeographicalRegion ( integer $countryCallingCode ) : |
||
getMetadataForRegion ( string $regionCode ) : |
Returns the metadata for the given region code or {@code null} if the region code is invalid or unknown. | |
getNationalSignificantNumber ( |
Gets the national significant number of the a phone number. Note a national significant number doesn't contain a national prefix or any formatting. | |
getNddPrefixForRegion ( string $regionCode, boolean $stripNonDigits ) : string | 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. | |
getNumberType ( |
Gets the type of a phone number. | |
getRegionCodeForCountryCode ( integer $countryCallingCode ) : string | 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). | |
getRegionCodeForNumber ( |
Returns the region where a phone number is from. This could be used for geocoding at the region level. | |
getRegionCodesForCountryCode ( integer $countryCallingCode ) : array | 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. | |
getSupportedGlobalNetworkCallingCodes ( ) : array | Convenience method to get a list of what global network calling codes the library has metadata for. | |
getSupportedRegions ( ) : array | Convenience method to get a list of what regions the library has metadata for. | |
isAlphaNumber ( string $number ) : boolean | Checks if the number is a valid vanity (alpha) number such as 800 MICROSOFT. A valid vanity number will start with at least 3 digits and will have three or more alpha characters. This does not do region-specific checks - to work out if this number is actually valid for a region, it should be parsed and methods such as {@link #isPossibleNumberWithReason} and {@link #isValidNumber} should be used. | |
isLeadingZeroPossible ( integer $countryCallingCode ) : boolean | Checks whether the country calling code is from a region whose national significant number could contain a leading zero. An example of such a region is Italy. Returns false if no metadata for the country is found. | |
isMobileNumberPortableRegion ( string $regionCode ) : boolean | Returns true if the supplied region supports mobile number portability. Returns false for invalid, unknown or regions that don't support mobile number portability. | |
isNANPACountry ( string $regionCode ) : boolean | Checks if this is a region under the North American Numbering Plan Administration (NANPA). | |
isNumberGeographical ( |
isNumberGeographical(PhoneNumber) | |
isNumberMatch ( $firstNumberIn, $secondNumberIn ) : integer | Takes two phone numbers and compares them for equality. | |
isNumberMatchingDesc ( string $nationalNumber, |
||
isPossibleNumber ( |
Check whether a phone number is a possible number given a number in the form of a string, and the region where the number could be dialed from. It provides a more lenient check than {@link #isValidNumber}. See {@link #isPossibleNumber(PhoneNumber)} for details. | |
isPossibleNumberWithReason ( |
Check whether a phone number is a possible number. It provides a more lenient check than
{@link #isValidNumber} in the following sense:
|
|
isValidNumber ( |
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. | |
isValidNumberForRegion ( |
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. | |
isViablePhoneNumber ( string $number ) : boolean | 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. | |
maybeExtractCountryCode ( string $number, |
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:
|
|
maybeStripInternationalPrefixAndNormalize ( string &$number, string $possibleIddPrefix ) : integer | 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. | |
maybeStripNationalPrefixAndCarrierCode ( string &$number, |
Strips any national prefix (such as 0, 1) present in the number provided. | |
normalize ( string &$number ) : string | Normalizes a string of characters representing a phone number. This performs the following conversions: Punctuation is stripped. | |
normalizeDiallableCharsOnly ( string $number ) : string | 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). | |
normalizeDigits ( string $number, boolean $keepNonDigits ) : string | ||
normalizeDigitsOnly ( $number ) : string | 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. | |
parse ( string $numberToParse, string $defaultRegion, |
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. | |
parseAndKeepRawInput ( string $numberToParse, string $defaultRegion, |
Parses a string and returns it in proto buffer format. This method differs from {@link #parse} in that it always populates the raw_input field of the protocol buffer with numberToParse as well as the country_code_source field. | |
resetInstance ( ) | Used for testing purposes only to reset the PhoneNumberUtil singleton to null. | |
setItalianLeadingZerosForPhoneNumber ( string $nationalNumber, |
A helper function to set the values related to leading zeros in a PhoneNumber. | |
truncateTooLongNumber ( |
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. |
Method | Description | |
---|---|---|
__construct ( libphonenumber\MetadataSourceInterface $metadataSource, $countryCallingCodeToRegionCodeMap ) | This class implements a singleton, so the only constructor is protected. | |
buildNationalNumberForParsing ( string $numberToParse, string &$nationalNumber ) | 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. | |
checkRegionForParsing ( string $numberToParse, string $defaultRegion ) : boolean | 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. | |
createExtnPattern ( string $singleExtnSymbols ) : string | Helper initialiser method to create the regular-expression pattern to match extensions, allowing the one-char extension symbols provided by {@code singleExtnSymbols}. | |
extractCountryCode ( string &$fullNumber, string &$nationalNumber ) : integer | Extracts country calling code from fullNumber, returns it and places the remaining number in nationalNumber. | |
formatNsn ( string $number, |
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. | |
formatNsnUsingPattern ( string $nationalNumber, |
Note that carrierCode is optional - if null or an empty string, no carrier code replacement will take place. | |
getCountryCodeForValidRegion ( string $regionCode ) : integer | 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. | |
getMetadataForRegionOrCallingCode ( integer $countryCallingCode, string $regionCode ) : |
||
getNumberDescByType ( |
||
getNumberTypeHelper ( string $nationalNumber, |
||
getRegionCodeForNumberFromRegionList ( |
||
getValidPhoneNumberPattern ( ) : string | 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. | |
hasFormattingPatternForNumber ( |
||
hasUnexpectedItalianLeadingZero ( |
Returns true if a number is from a region whose national significant number couldn't contain a leading zero, but has the italian_leading_zero field set to true. | |
hasValidCountryCallingCode ( integer $countryCallingCode ) : boolean | Helper function to check the country calling code is valid. | |
init ( ) | ||
initAlphaPhoneMappings ( ) | ||
initCapturingExtnDigits ( ) | ||
initDiallableCharMappings ( ) | ||
initExtnPattern ( ) | ||
initExtnPatterns ( ) | ||
initMobileTokenMappings ( ) | ||
initValidStartCharPattern ( ) | ||
isNationalNumberSuffixOfTheOther ( |
Returns true when one national number is the suffix of the other or both are the same. | |
isValidRegionCode ( string $regionCode ) : boolean | Helper function to check region code is not unknown or null. | |
maybeAppendFormattedExtension ( |
Appends the formatted extension of a phone number to formattedNumber, if the phone number had an extension specified. | |
maybeStripExtension ( string &$number ) : string | 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. | |
normalizeHelper ( string $number, array $normalizationReplacements, boolean $removeNonMatches ) : string | Normalizes a string of characters representing a phone number by replacing all characters found in the accompanying map with the values therein, and stripping all other characters if removeNonMatches is true. | |
parseHelper ( string $numberToParse, string $defaultRegion, boolean $keepRawInput, boolean $checkRegion, |
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"). | |
parsePrefixAsIdd ( string $iddPattern, string &$number ) : boolean | Strips the IDD from the start of the number if present. Helper function used by maybeStripInternationalPrefixAndNormalize. | |
prefixNumberWithCountryCallingCode ( integer $countryCallingCode, integer $numberFormat, string &$formattedNumber ) | A helper function that is used by format and formatByPattern. | |
rawInputContainsNationalPrefix ( string $rawInput, string $nationalPrefix, string $regionCode ) : boolean | 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. | |
stringEndsWithString ( $hayStack, $needle ) | ||
testNumberLength ( string $number, |
Helper method to check a number against possible lengths for this number, and determine whether it matches, or is too short or too long. Currently, if a number pattern suggests that numbers of length 7 and 10 are possible, and a number in between these possible lengths is entered, such as of length 8, this will return TOO_LONG. |
protected __construct ( libphonenumber\MetadataSourceInterface $metadataSource, $countryCallingCodeToRegionCodeMap ) | ||
$metadataSource | libphonenumber\MetadataSourceInterface | |
$countryCallingCodeToRegionCodeMap |
protected buildNationalNumberForParsing ( string $numberToParse, string &$nationalNumber ) | ||
$numberToParse | string | |
$nationalNumber | string |
public canBeInternationallyDialled ( |
||
$number | the phone-number for which we want to know whether it is diallable from outside the region | |
return | boolean |
public static convertAlphaCharactersInNumber ( string $number ) : string | ||
$number | string | |
return | string |
protected static createExtnPattern ( string $singleExtnSymbols ) : string | ||
$singleExtnSymbols | string | |
return | string |
public static extractPossibleNumber ( integer $number ) : string | ||
$number | integer | 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 formatByPattern ( |
||
$number | the phone number to be formatted | |
$numberFormat | integer | the format the phone number should be formatted into |
$userDefinedFormats | array | formatting rules specified by clients |
return | String | the formatted phone number |
public formatInOriginalFormat ( |
||
$number | the phone number that needs to be formatted in its original number format | |
$regionCallingFrom | string | 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 formatNationalNumberWithCarrierCode ( |
||
$number | the phone number to be formatted | |
$carrierCode | string | 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} |
Use {@link #formatNationalNumberWithCarrierCode} instead if the carrier code passed in should take precedence over the number's {@code preferredDomesticCarrierCode} when formatting.
public formatNationalNumberWithPreferredCarrierCode ( |
||
$number | the phone number to be formatted | |
$fallbackCarrierCode | string | 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 formatNumberForMobileDialing ( |
||
$number | the phone number to be formatted | |
$regionCallingFrom | string | the region where the call is being placed |
$withFormatting | boolean | whether the number should be returned with formatting symbols, such as spaces and dashes. |
return | string | the formatted phone number |
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.
public formatOutOfCountryCallingNumber ( |
||
$number | the phone number to be formatted | |
$regionCallingFrom | string | the region where the call is being placed |
return | string | the formatted phone number |
Caveats:
public formatOutOfCountryKeepingAlphaChars ( |
||
$number | the phone number that needs to be formatted | |
$regionCallingFrom | String | the region where the call is being placed |
return | String | the formatted phone number |
public static formattingRuleHasFirstGroupOnly ( string $nationalPrefixFormattingRule ) : boolean | ||
$nationalPrefixFormattingRule | string | |
return | boolean |
public getCountryCodeForRegion ( string $regionCode ) : integer | ||
$regionCode | string | the region that we want to get the country calling code for |
return | integer | the country calling code for the region denoted by regionCode |
protected getCountryCodeForValidRegion ( string $regionCode ) : integer | ||
$regionCode | string | the region that we want to get the country calling code for |
return | integer | the country calling code for the region denoted by regionCode |
public static getCountryMobileToken ( integer $countryCallingCode ) : string | ||
$countryCallingCode | integer | 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 getExampleNumber ( $regionCode ) : |
||
return | a valid fixed-line number for the specified region. Returns null when the metadata does not contain such information, or the region 001 is passed in. For 001 (representing non-geographical numbers), call {@link #getExampleNumberForNonGeoEntity} instead. |
public getExampleNumberForNonGeoEntity ( integer $countryCallingCode ) : |
||
$countryCallingCode | integer | the country calling code for a non-geographical entity |
return | 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 getExampleNumberForType ( string | integer $regionCodeOrType, integer $type = null ) : |
||
$regionCodeOrType | string | integer | the region for which an example number is needed |
$type | integer | the PhoneNumberType of number that is needed |
return | a valid number for the specified region and type. Returns null when the metadata does not contain such information or if an invalid region or region 001 was entered. For 001 (representing non-geographical numbers), call {@link #getExampleNumberForNonGeoEntity} instead. If $regionCodeOrType is the only parameter supplied, then a valid number for the specified number type will be returned that may belong to any country. |
The {@link PhoneNumberUtil} is implemented as a singleton. Therefore, calling getInstance multiple times will only result in one instance being created.
public static getInstance ( string $baseFileLocation = self::META_DATA_FILE_PREFIX, array $countryCallingCodeToRegionCodeMap = null, libphonenumber\MetadataLoaderInterface $metadataLoader = null, libphonenumber\MetadataSourceInterface $metadataSource = null ) : |
||
$baseFileLocation | string | |
$countryCallingCodeToRegionCodeMap | array | |
$metadataLoader | libphonenumber\MetadataLoaderInterface | |
$metadataSource | libphonenumber\MetadataSourceInterface | |
return | instance |
public getInvalidExampleNumber ( string $regionCode ) : |
||
$regionCode | string | The region for which an example number is needed |
return | An invalid number for the specified region. Returns null when an unsupported region or the region 001 (Earth) is passed in. |
$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:
public getLengthOfGeographicalAreaCode ( |
||
$number | PhoneNumber object for which clients want to know the length of the area code. | |
return | integer | the length of area code of the PhoneNumber object passed in. |
$phoneUtil = PhoneNumberUtil::getInstance();
$number = $phoneUtil->parse("18002530000", "US");
$nationalSignificantNumber = $phoneUtil->getNationalSignificantNumber($number);
$nationalDestinationCodeLength = $phoneUtil->getLengthOfNationalDestinationCode($number);
if ($nationalDestinationCodeLength > 0) {
$nationalDestinationCode = substr($nationalSignificantNumber, 0, $nationalDestinationCodeLength);
$subscriberNumber = substr($nationalSignificantNumber, $nationalDestinationCodeLength);
} else {
$nationalDestinationCode = "";
$subscriberNumber = $nationalSignificantNumber;
}
Refer to the unit tests to see the difference between this function and
{@link #getLengthOfGeographicalAreaCode}.
public getLengthOfNationalDestinationCode ( |
||
$number | the PhoneNumber object for which clients want to know the length of the NDC. | |
return | integer | the length of NDC of the PhoneNumber object passed in. |
public getMetadataForNonGeographicalRegion ( integer $countryCallingCode ) : |
||
$countryCallingCode | integer | |
return |
public getMetadataForRegion ( string $regionCode ) : |
||
$regionCode | string | |
return |
protected getMetadataForRegionOrCallingCode ( integer $countryCallingCode, string $regionCode ) : |
||
$countryCallingCode | integer | |
$regionCode | string | |
return |
public getNationalSignificantNumber ( |
||
$number | the phone number for which the national significant number is needed | |
return | string | the national significant number of the PhoneNumber object passed in |
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.
public getNddPrefixForRegion ( string $regionCode, boolean $stripNonDigits ) : string | ||
$regionCode | string | the region that we want to get the dialling prefix for |
$stripNonDigits | boolean | true to strip non-digits from the national dialling prefix |
return | string | the dialling prefix for the region denoted by regionCode |
protected getNumberDescByType ( |
||
$metadata | ||
$type | integer | PhoneNumberType |
return |
public getNumberType ( |
||
$number | the number the phone number that we want to know the type | |
return | integer | PhoneNumberType the type of the phone number |
protected getNumberTypeHelper ( string $nationalNumber, |
||
$nationalNumber | string | |
$metadata | ||
return | integer | PhoneNumberType constant |
public getRegionCodeForCountryCode ( integer $countryCallingCode ) : string | ||
$countryCallingCode | integer | |
return | string |
public getRegionCodeForNumber ( |
||
$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 getRegionCodesForCountryCode ( integer $countryCallingCode ) : array | ||
$countryCallingCode | integer | |
return | array |
public getSupportedGlobalNetworkCallingCodes ( ) : array | ||
return | array |
public getSupportedRegions ( ) : array | ||
return | array |
protected static getValidPhoneNumberPattern ( ) : string | ||
return | string |
protected hasFormattingPatternForNumber ( |
||
$number | ||
return | boolean |
protected hasUnexpectedItalianLeadingZero ( |
||
$number | ||
return | boolean |
protected hasValidCountryCallingCode ( integer $countryCallingCode ) : boolean | ||
$countryCallingCode | integer | |
return | boolean |
public isAlphaNumber ( string $number ) : boolean | ||
$number | string | the number that needs to be checked |
return | boolean | true if the number is a valid vanity number |
public isLeadingZeroPossible ( integer $countryCallingCode ) : boolean | ||
$countryCallingCode | integer | |
return | boolean |
public isMobileNumberPortableRegion ( string $regionCode ) : boolean | ||
$regionCode | string | the region for which we want to know whether it supports mobile number portability or not. |
return | boolean |
public isNANPACountry ( string $regionCode ) : boolean | ||
$regionCode | string | |
return | boolean | true if regionCode is one of the regions under NANPA |
protected isNationalNumberSuffixOfTheOther ( |
||
$firstNumber | ||
$secondNumber | ||
return | boolean |
public isNumberGeographical ( |
||
$phoneNumberObjOrType | A PhoneNumber object, or a PhoneNumberType integer | |
$countryCallingCode | integer | null | Used when passing a PhoneNumberType |
return | boolean |
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.
public isNumberMatch ( $firstNumberIn, $secondNumberIn ) : integer | ||
$firstNumberIn | PhoneNumber|string First number to compare. If it is a string it can contain formatting, and can have country calling code specified with + at the start. | |
$secondNumberIn | PhoneNumber|string Second number to compare. If it is a string it can contain formatting, and can have country calling code specified with + at the start. | |
return | integer | {MatchType} NOT_A_NUMBER, NO_MATCH, |
public isNumberMatchingDesc ( string $nationalNumber, |
||
$nationalNumber | string | |
$numberDesc | ||
return | boolean |
This method first parses the number, then invokes {@link #isPossibleNumber(PhoneNumber)} with the resultant PhoneNumber object.
public isPossibleNumber ( |
||
$number | the number that needs to be checked, in the form of a string | |
$regionDialingFrom | string | the region that we are expecting the number to be dialed from. Note this is different from the region where the number belongs. For example, the number +1 650 253 0000 is a number that belongs to US. When written in this form, it can be dialed from any region. When it is written as 00 1 650 253 0000, it can be dialed from any region which uses an international dialling prefix of 00. When it is written as 650 253 0000, it can only be dialed from within the US, and when written as 253 0000, it can only be dialed from within a smaller area in the US (Mountain View, CA, to be more specific). |
return | boolean | true if the number is possible |
public isPossibleNumberWithReason ( |
||
$number | the number that needs to be checked | |
return | integer | a ValidationResult object which indicates whether the number is possible |
public isValidNumber ( |
||
$number | the phone number that we want to validate | |
return | boolean | that indicates whether the number is of a valid pattern |
public isValidNumberForRegion ( |
||
$number | the phone number that we want to validate | |
$regionCode | string | the region that we want to validate the phone number for |
return | boolean | that indicates whether the number is of a valid pattern |
protected isValidRegionCode ( string $regionCode ) : boolean | ||
$regionCode | string | |
return | boolean |
public static isViablePhoneNumber ( string $number ) : boolean | ||
$number | string | to be checked for viability as a phone number |
return | boolean | true if the number could be a phone number of some sort, otherwise false |
public maybeExtractCountryCode ( string $number, |
||
$number | string | non-normalized telephone number that we wish to extract a country calling code from - may begin with '+' |
$defaultRegionMetadata | metadata about the region this number may be from | |
$nationalNumber | string | 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. |
$keepRawInput | boolean | true if the country_code_source and preferred_carrier_code fields of phoneNumber should be populated. |
$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 | integer | the country calling code extracted or 0 if none could be extracted |
protected maybeStripExtension ( string &$number ) : string | ||
$number | string | the non-normalized telephone number that we wish to strip the extension from |
return | string | the phone extension |
public maybeStripInternationalPrefixAndNormalize ( string &$number, string $possibleIddPrefix ) : integer | ||
$number | string | the non-normalized telephone number that we wish to strip any international dialing prefix from. |
$possibleIddPrefix | string | string the international direct dialing prefix from the region we think this number may be dialed in |
return | integer | 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 maybeStripNationalPrefixAndCarrierCode ( string &$number, |
||
$number | string | the normalized telephone number that we wish to strip any national dialing prefix from |
$metadata | the metadata for the region that we think this number is from | |
$carrierCode | string | a place to insert the carrier code if one is extracted |
return | boolean | true if a national prefix or carrier code (or both) could be extracted. |
public static normalizeDiallableCharsOnly ( string $number ) : string | ||
$number | string | a string of characters representing a phone number |
return | string | the normalized string version of the phone number |
public static normalizeDigitsOnly ( $number ) : string | ||
$number | string a string of characters representing a phone number | |
return | string | the normalized string version of the phone number |
protected static normalizeHelper ( string $number, array $normalizationReplacements, boolean $removeNonMatches ) : string | ||
$number | string | a string of characters representing a phone number |
$normalizationReplacements | array | a mapping of characters to what they should be replaced by in the normalized version of the phone number |
$removeNonMatches | boolean | indicates whether characters that are not able to be replaced should be stripped from the number. If this is false, they will be left unchanged in the number. |
return | string | the normalized string version of the phone number |
This method will throw a {@link NumberParseException} if the number is not considered to be a possible number. Note that validation of whether the number is actually a valid number for a particular region is not performed. This can be done separately with {@link #isValidnumber}.
public parse ( string $numberToParse, string $defaultRegion, |
||
$numberToParse | string | number that we are attempting to parse. This can contain formatting such as +, ( and -, as well as a phone number extension. |
$defaultRegion | string | 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. |
$phoneNumber | ||
$keepRawInput | boolean | |
return | a phone number proto buffer filled with the parsed number |
public parseAndKeepRawInput ( string $numberToParse, string $defaultRegion, |
||
$numberToParse | string | 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. |
$defaultRegion | string | 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. |
$phoneNumber | ||
return | a phone number proto buffer filled with the parsed number |
public static resetInstance ( ) |
public static setItalianLeadingZerosForPhoneNumber ( string $nationalNumber, |
||
$nationalNumber | string | |
$phoneNumber |
protected testNumberLength ( string $number, |
||
$number | string | |
$phoneNumberDesc | ||
return | integer | ValidationResult |
public truncateTooLongNumber ( |
||
$number | a PhoneNumber object which contains a number that is too long to be valid. | |
return | boolean | true if a valid phone number can be successfully extracted. |
protected static array $ALL_PLUS_NUMBER_GROUPING_SYMBOLS | ||
return | array |
protected static array $ALPHA_MAPPINGS | ||
return | array |
protected static array $ALPHA_PHONE_MAPPINGS | ||
return | array |
protected static String $EXTN_PATTERNS_FOR_PARSING | ||
return | String |
protected static array $GEO_MOBILE_COUNTRIES | ||
return | array |
protected static array $GEO_MOBILE_COUNTRIES_WITHOUT_MOBILE_AREA_CODES | ||
return | array |
protected static $MIN_LENGTH_PHONE_NUMBER_PATTERN |
protected static array $MOBILE_TOKEN_MAPPINGS | ||
return | array |
protected static $SECOND_NUMBER_START_PATTERN |
protected static $UNWANTED_END_CHAR_PATTERN |
protected static string $VALID_PHONE_NUMBER | ||
return | string |
protected static $VALID_PHONE_NUMBER_PATTERN |
protected static $VALID_START_CHAR_PATTERN |
protected static array $asciiDigitMappings | ||
return | array |
protected array $countryCallingCodeToRegionCodeMap | ||
return | array |
protected array $countryCodesForNonGeographicalRegion | ||
return | array |
protected static PhoneNumberUtil,libphonenumber $instance | ||
return |
protected MetadataSourceInterface,libphonenumber $metadataSource | ||
return | libphonenumber\MetadataSourceInterface |
protected array $nanpaRegions | ||
return | array |
protected array $supportedRegions | ||
return | array |