PhoneNumberUtil - libphonenumber for PHP

Overview

The PhoneNumberUtil class is the main entry point for all phone number operations. It provides functionality for:

Parsing phone numbers from strings
Validating phone numbers
Formatting phone numbers in various formats
Getting information about phone numbers (type, region, etc.)

This class is implemented as a singleton for performance optimization.

Getting an Instance

getInstance()

Returns the singleton instance of PhoneNumberUtil. The instance is loaded with phone number metadata for commonly used regions.

public static function getInstance(
    string $metadataLocation = 'libphonenumber\\data\\PhoneNumberMetadata_',
    array $countryCallingCodeToRegionCodeMap = CountryCodeToRegionCodeMap::COUNTRY_CODE_TO_REGION_CODE_MAP
): PhoneNumberUtil

metadataLocation

string

default:"libphonenumber\\\\data\\\\PhoneNumberMetadata_"

The location of the metadata files (optional)

countryCallingCodeToRegionCodeMap

array

Mapping of country codes to region codes (optional)

Returns: PhoneNumberUtil instance Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

Calling getInstance() multiple times returns the same instance (singleton pattern).

Parsing Methods

parse()

Parses a string and returns it as a PhoneNumber object. This is the primary method for converting string phone numbers into structured objects.

public function parse(
    string $numberToParse,
    ?string $defaultRegion
): PhoneNumber

numberToParse

string

required

The phone number to parse. Can contain formatting such as +, (, and -, as well as extensions.

defaultRegion

string|null

required

The region code (e.g., ‘GB’, ‘US’) used when the number is not in international format. Can be null if the number starts with ’+’.

Returns: PhoneNumber object Throws: NumberParseException if the number cannot be parsed (too short/long, invalid region, etc.) Examples:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

// Parse international number (no region needed)
$phoneNumber = $phoneUtil->parse('+44 117 496 0123', null);

The parse() method does not validate whether the number is actually valid - it only checks if it can be parsed. Use validation methods like isValidNumber() to verify validity.

parseAndKeepRawInput()

Similar to parse(), but also populates the rawInput and countryCodeSource fields of the returned PhoneNumber object.

public function parseAndKeepRawInput(
    string $numberToParse,
    ?string $defaultRegion,
    ?PhoneNumber $phoneNumber = null
): PhoneNumber

numberToParse

string

required

The phone number to parse. Can be in various formats including RFC3966.

defaultRegion

string|null

required

The region code used if the number is not in international format.

phoneNumber

PhoneNumber|null

default:"null"

Optional PhoneNumber object to populate (creates new one if null).

Returns: PhoneNumber object with raw input preserved Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parseAndKeepRawInput('1-800-GOOG-411', 'US');

// Raw input is preserved
echo $phoneNumber->getRawInput(); // "1-800-GOOG-411"

Validation Methods

isValidNumber()
isValidNumberForRegion()
isPossibleNumber()
isPossibleNumberWithReason()

isValidNumber()

Tests whether a phone number matches a valid pattern.

public function isValidNumber(PhoneNumber $number): bool

number

PhoneNumber

required

The phone number object to validate

Returns: bool - true if valid, false otherwiseExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('0117 496 0123', 'GB');

if ($phoneUtil->isValidNumber($phoneNumber)) {
    echo "Valid number!";
}

This method validates number patterns only. It cannot verify if a number is actually in use by checking with telecommunication providers.

isValidNumberForRegion()

Tests whether a phone number is valid for a specific region.

public function isValidNumberForRegion(
    PhoneNumber $number,
    string $regionCode
): bool

number

PhoneNumber

required

The phone number to validate

regionCode

string

required

The region code to validate against (e.g., ‘GB’, ‘US’)

Returns: bool - true if valid for the regionExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('+44 117 496 0123', null);

var_dump($phoneUtil->isValidNumberForRegion($phoneNumber, 'GB')); // true
var_dump($phoneUtil->isValidNumberForRegion($phoneNumber, 'FR')); // false

isPossibleNumber()

Checks if a number is possible (has valid length). More lenient than isValidNumber().

// With PhoneNumber object
public function isPossibleNumber(PhoneNumber $number): bool

// With string and region
public function isPossibleNumber(string $number, string $regionCode): bool

number

PhoneNumber|string

required

The phone number to check (as object or string)

regionCode

string

Required when using string format

Returns: bool - true if the number is possibleExamples:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

// With PhoneNumber object
$phoneNumber = $phoneUtil->parse('0117 496 0123', 'GB');
var_dump($phoneUtil->isPossibleNumber($phoneNumber)); // true

// With string
var_dump($phoneUtil->isPossibleNumber('01174960123', 'GB')); // true

isPossibleNumberWithReason()

Returns detailed reason why a number is or isn’t possible.

public function isPossibleNumberWithReason(
    PhoneNumber $number
): ValidationResult

number

PhoneNumber

required

The phone number to check

Returns: ValidationResult enum with values:

IS_POSSIBLE - Number is valid
IS_POSSIBLE_LOCAL_ONLY - Valid only for local dialing
INVALID_COUNTRY_CODE - Invalid country code
TOO_SHORT - Number too short
TOO_LONG - Number too long
INVALID_LENGTH - Invalid length

Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('0117 496 0123', 'GB');

$result = $phoneUtil->isPossibleNumberWithReason($phoneNumber);
// Returns ValidationResult::IS_POSSIBLE

Formatting Methods

format()
formatOutOfCountryCallingNumber()
formatNumberForMobileDialing()
formatNationalNumberWithCarrierCode()

format()

Formats a phone number in the specified format using default rules.

public function format(
    PhoneNumber $number,
    PhoneNumberFormat $numberFormat
): string

number

PhoneNumber

required

The phone number to format

numberFormat

PhoneNumberFormat

required

The format to use: E164, INTERNATIONAL, NATIONAL, or RFC3966

Returns: string - The formatted phone numberExamples:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('0117 496 0123', 'GB');

// E164 format (no spaces, with +)
echo $phoneUtil->format($phoneNumber, \libphonenumber\PhoneNumberFormat::E164);
// "+441174960123"

// International format (human-readable)
echo $phoneUtil->format($phoneNumber, \libphonenumber\PhoneNumberFormat::INTERNATIONAL);
// "+44 117 496 0123"

// National format (as dialed within country)
echo $phoneUtil->format($phoneNumber, \libphonenumber\PhoneNumberFormat::NATIONAL);
// "0117 496 0123"

// RFC3966 format (tel: URI)
echo $phoneUtil->format($phoneNumber, \libphonenumber\PhoneNumberFormat::RFC3966);
// "tel:+44-117-496-0123"

formatOutOfCountryCallingNumber()

Formats a number as it would be dialed from another country.

public function formatOutOfCountryCallingNumber(
    PhoneNumber $number,
    string $regionCallingFrom
): string

number

PhoneNumber

required

The phone number to format

regionCallingFrom

string

required

The region code of the country dialing from

Returns: string - The formatted number with appropriate international prefixExamples:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('0117 496 0123', 'GB');

// Dialing from France (uses 00 prefix)
echo $phoneUtil->formatOutOfCountryCallingNumber($phoneNumber, 'FR');
// "00 44 117 496 0123"

// Dialing from US (uses 011 prefix)
echo $phoneUtil->formatOutOfCountryCallingNumber($phoneNumber, 'US');
// "011 44 117 496 0123"

// Dialing from same country (GB)
echo $phoneUtil->formatOutOfCountryCallingNumber($phoneNumber, 'GB');
// "0117 496 0123"

formatNumberForMobileDialing()

Formats a number for mobile dialing from a specific region.

public function formatNumberForMobileDialing(
    PhoneNumber $number,
    string $regionCallingFrom,
    bool $withFormatting
): string

number

PhoneNumber

required

The phone number to format

regionCallingFrom

string

required

The region dialing from

withFormatting

bool

required

Whether to include formatting (spaces, dashes)

Returns: string - Formatted number for mobile dialing, or empty string if cannot be dialedExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$ausNumber = $phoneUtil->parse('1300123456', 'AU');

// With formatting
echo $phoneUtil->formatNumberForMobileDialing($ausNumber, 'AU', true);
// "1300 123 456"

// Without formatting
echo $phoneUtil->formatNumberForMobileDialing($ausNumber, 'AU', false);
// "1300123456"

// Cannot dial from US (returns empty)
echo $phoneUtil->formatNumberForMobileDialing($ausNumber, 'US', true);
// ""

formatNationalNumberWithCarrierCode()

Formats a number in national format with a specific carrier code.

public function formatNationalNumberWithCarrierCode(
    PhoneNumber $number,
    string $carrierCode
): string

number

PhoneNumber

required

The phone number to format

carrierCode

string

required

The carrier code to use (empty string for none)

Returns: string - Formatted number with carrier codeExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$arNumber = $phoneUtil->parse('92234654321', 'AR');

echo $phoneUtil->formatNationalNumberWithCarrierCode($arNumber, '14');
// "02234 14 65-4321"

Information Methods

getNumberType()
getRegionCodeForNumber()
getNationalSignificantNumber()
isNumberGeographical()
canBeInternationallyDialled()

getNumberType()

Returns the type of phone number (mobile, fixed-line, etc.).

public function getNumberType(PhoneNumber $number): PhoneNumberType

number

PhoneNumber

required

The phone number to check

Returns: PhoneNumberType enum with values:

FIXED_LINE - Fixed-line number
MOBILE - Mobile number
FIXED_LINE_OR_MOBILE - Could be either
TOLL_FREE - Toll-free number
PREMIUM_RATE - Premium rate number
SHARED_COST - Shared cost number
VOIP - VoIP number
PERSONAL_NUMBER - Personal number
PAGER - Pager number
UAN - Universal Access Number
VOICEMAIL - Voicemail access number
UNKNOWN - Unknown type

Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('0117 496 0123', 'GB');

$type = $phoneUtil->getNumberType($phoneNumber);
// Returns PhoneNumberType::FIXED_LINE

getRegionCodeForNumber()

Returns the region code for a phone number.

public function getRegionCodeForNumber(
    PhoneNumber $number
): ?string

number

PhoneNumber

required

The phone number

Returns: string|null - The region code (e.g., ‘GB’, ‘US’) or null if no matchExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('+44 117 496 0123', null);

echo $phoneUtil->getRegionCodeForNumber($phoneNumber);
// "GB"

getNationalSignificantNumber()

Gets the national significant number (without country code or formatting).

public function getNationalSignificantNumber(
    PhoneNumber $number
): string

number

PhoneNumber

required

The phone number

Returns: string - The national significant numberExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('+44 117 496 0123', null);

echo $phoneUtil->getNationalSignificantNumber($phoneNumber);
// "1174960123"

isNumberGeographical()

Tests whether a phone number has a geographical association.

// With PhoneNumber object
public function isNumberGeographical(
    PhoneNumber $phoneNumber
): bool

// With type and country code
public function isNumberGeographical(
    PhoneNumberType $phoneNumberType,
    int $countryCallingCode
): bool

phoneNumber

PhoneNumber|PhoneNumberType

required

Phone number or type to check

countryCallingCode

int

Required when passing PhoneNumberType

Returns: bool - true if the number is geographicalExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$phoneNumber = $phoneUtil->parse('0117 496 0123', 'GB');

var_dump($phoneUtil->isNumberGeographical($phoneNumber));
// bool(true) - fixed-line numbers are geographical

canBeInternationallyDialled()

Returns whether a number can be dialed internationally.

public function canBeInternationallyDialled(
    PhoneNumber $number
): bool

number

PhoneNumber

required

The phone number to check

Returns: bool - true if can be dialed internationallyExample:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

// UK number (can be dialed internationally)
$ukNumber = $phoneUtil->parse('0117 496 0123', 'GB');
var_dump($phoneUtil->canBeInternationallyDialled($ukNumber));
// bool(true)

// Australian 1300 number (cannot be dialed internationally)
$ausNumber = $phoneUtil->parse('1300123456', 'AU');
var_dump($phoneUtil->canBeInternationallyDialled($ausNumber));
// bool(false)

Region and Country Code Methods

getCountryCodeForRegion()

Returns the country calling code for a region.

public function getCountryCodeForRegion(string $regionCode): int

regionCode

string

required

The region code (e.g., ‘NZ’, ‘US’)

Returns: int - The country calling code Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

echo $phoneUtil->getCountryCodeForRegion('NZ'); // 64
echo $phoneUtil->getCountryCodeForRegion('US'); // 1
echo $phoneUtil->getCountryCodeForRegion('GB'); // 44

getRegionCodeForCountryCode()

Returns the region code for a country calling code.

public function getRegionCodeForCountryCode(
    int $countryCallingCode
): string

countryCallingCode

int

required

The country calling code

Returns: string - The region code, ‘001’ for non-geographical, or ‘ZZ’ for unknown Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

echo $phoneUtil->getRegionCodeForCountryCode(44); // "GB"
echo $phoneUtil->getRegionCodeForCountryCode(1);  // "US" (main region for NANPA)

getRegionCodesForCountryCode()

Returns all region codes that match a country calling code.

public function getRegionCodesForCountryCode(
    int $countryCallingCode
): array

countryCallingCode

int

required

The country calling code

Returns: array<string> - Array of region codes Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

var_dump($phoneUtil->getRegionCodesForCountryCode(44));
// array(1) { [0]=> string(2) "GB" }

var_dump($phoneUtil->getRegionCodesForCountryCode(1));
// array(25) { [0]=> "US", [1]=> "AG", [2]=> "AI", ... } (NANPA countries)

getSupportedRegions()

Returns all region codes the library supports.

public function getSupportedRegions(): array

Returns: array<string> - Array of two-letter region codes Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$regions = $phoneUtil->getSupportedRegions();
// array("US", "GB", "DE", "FR", ...)

Example Number Methods

getExampleNumber()

Returns an example phone number for a region.

public function getExampleNumber(string $regionCode): ?PhoneNumber

regionCode

string

required

The region code

Returns: PhoneNumber|null - Example number or null if none available Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$example = $phoneUtil->getExampleNumber('GB');
// PhoneNumber: Country Code: 44 National Number: 1212345678

getExampleNumberForType()

Returns an example number for a region and type.

// For specific region and type
public function getExampleNumberForType(
    string $regionCode,
    PhoneNumberType $type
): ?PhoneNumber

// For any region with type
public function getExampleNumberForType(
    PhoneNumberType $type
): ?PhoneNumber

regionCode

string

The region code (optional if just type provided)

type

PhoneNumberType

required

The number type

Returns: PhoneNumber|null - Example number or null Examples:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

// Get mobile number for GB
$mobile = $phoneUtil->getExampleNumberForType('GB', \libphonenumber\PhoneNumberType::MOBILE);
// PhoneNumber: Country Code: 44 National Number: 7400123456

// Get any mobile number
$anyMobile = $phoneUtil->getExampleNumberForType(\libphonenumber\PhoneNumberType::MOBILE);
// PhoneNumber: Country Code: 1 National Number: 2015555555

Utility Methods

findNumbers()

Finds phone numbers in text.

public function findNumbers(
    string $text,
    ?string $defaultRegion,
    ?AbstractLeniency $leniency = null,
    int $maxTries = PHP_INT_MAX
): PhoneNumberMatcher

text

string

required

The text to search

defaultRegion

string|null

required

Default region for numbers without country code

leniency

AbstractLeniency|null

default:"Leniency::VALID()"

Leniency level for matching

maxTries

int

default:"PHP_INT_MAX"

Maximum number of matches

Returns: PhoneNumberMatcher - Iterator for matches Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$text = "Call me at +44 117 496 0123 or 0207 123 4567";

foreach ($phoneUtil->findNumbers($text, 'GB') as $match) {
    echo $match->rawString() . "\n";
}
// +44 117 496 0123
// 0207 123 4567

getAsYouTypeFormatter()

Gets a formatter for as-you-type formatting.

public function getAsYouTypeFormatter(string $regionCode): AsYouTypeFormatter

regionCode

string

required

The region code

Returns: AsYouTypeFormatter instance Example:

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$formatter = $phoneUtil->getAsYouTypeFormatter('US');

echo $formatter->inputDigit('2'); // 2
echo $formatter->inputDigit('0'); // 20
echo $formatter->inputDigit('1'); // 201
echo $formatter->inputDigit('5'); // (201) 5

normalize()

Normalizes a phone number string.

public static function normalize(string $number): string

number

string

required

The phone number to normalize

Returns: string - Normalized number (digits only) Example:

echo \libphonenumber\PhoneNumberUtil::normalize("(201) 555-0123");
// "2015550123"

Core Classes

Formatting

Mapping & Geocoding

Utilities

​Overview

​Getting an Instance

​getInstance()

​Parsing Methods

​parse()

​parseAndKeepRawInput()

​Validation Methods

​isValidNumber()

​isValidNumberForRegion()

​isPossibleNumber()

​isPossibleNumberWithReason()

​Formatting Methods

​format()

​formatOutOfCountryCallingNumber()

​formatNumberForMobileDialing()

​formatNationalNumberWithCarrierCode()

​Information Methods

​getNumberType()

​getRegionCodeForNumber()

​getNationalSignificantNumber()

​isNumberGeographical()

​canBeInternationallyDialled()

​Region and Country Code Methods

​getCountryCodeForRegion()

​getRegionCodeForCountryCode()

​getRegionCodesForCountryCode()

​getSupportedRegions()

​Example Number Methods

​getExampleNumber()

​getExampleNumberForType()

​Utility Methods

​findNumbers()

​getAsYouTypeFormatter()

​normalize()

​See Also

Build docs developers (and LLMs) love

Overview

Getting an Instance

getInstance()

Parsing Methods

parse()

parseAndKeepRawInput()

Validation Methods

isValidNumber()

isValidNumberForRegion()

isPossibleNumber()

isPossibleNumberWithReason()

Formatting Methods

format()

formatOutOfCountryCallingNumber()

formatNumberForMobileDialing()

formatNationalNumberWithCarrierCode()

Information Methods

getNumberType()

getRegionCodeForNumber()

getNationalSignificantNumber()

isNumberGeographical()

canBeInternationallyDialled()

Region and Country Code Methods

getCountryCodeForRegion()

getRegionCodeForCountryCode()

getRegionCodesForCountryCode()

getSupportedRegions()

Example Number Methods

getExampleNumber()

getExampleNumberForType()

Utility Methods

findNumbers()

getAsYouTypeFormatter()

normalize()

See Also