PhoneNumber

Overview

The PhoneNumber class is a data structure that represents a parsed phone number. It stores all components of a phone number including:

Country calling code
National number
Extension
Leading zeros (for Italian-style numbers)
Raw input (when using parseAndKeepRawInput())
Country code source information
Preferred carrier code

It is not recommended to create PhoneNumber objects directly. Instead, use PhoneNumberUtil::parse() to parse a number string and return a properly populated PhoneNumber object.

Creating PhoneNumber Objects

Recommended: Using PhoneNumberUtil

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

Manual Creation (Not Recommended)

If you need to manually construct a PhoneNumber object:

$phoneNumber = new \libphonenumber\PhoneNumber();
$phoneNumber->setCountryCode(44);
$phoneNumber->setNationalNumber('1174960123');

PhoneNumber Structure

When you parse a number, the resulting PhoneNumber object contains:

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

var_dump($phoneNumber);

Output:

object(libphonenumber\PhoneNumber) {
  ["countryCode":private] => int(44)
  ["nationalNumber":private] => string(10) "1174960123"
  ["extension":private] => NULL
  ["italianLeadingZero":private] => NULL
  ["rawInput":private] => NULL
  ["countryCodeSource":private] => NULL
  ["preferredDomesticCarrierCode":private] => NULL
  ["hasNumberOfLeadingZeros":private] => bool(false)
  ["numberOfLeadingZeros":private] => int(1)
}

Properties and Methods

Country Code

getCountryCode()
setCountryCode()
hasCountryCode()
clearCountryCode()

public function getCountryCode(): ?int

Returns the country calling code (e.g., 1 for NANPA countries, 44 for UK).Returns: int|null - The country code or null if not setExample:

$phoneNumber = $phoneUtil->parse('+44 117 496 0123', null);
echo $phoneNumber->getCountryCode(); // 44

public function setCountryCode(int $value): static

Sets the country calling code.

value

int

required

The country calling code

Returns: static - The PhoneNumber instance (for method chaining)Example:

$phoneNumber = new \libphonenumber\PhoneNumber();
$phoneNumber->setCountryCode(44);

public function hasCountryCode(): bool

Checks if country code is set.Returns: bool - true if setExample:

if ($phoneNumber->hasCountryCode()) {
    echo "Country code: " . $phoneNumber->getCountryCode();
}

public function clearCountryCode(): static

Clears the country code.Returns: static - The PhoneNumber instanceExample:

$phoneNumber->clearCountryCode();

National Number

getNationalNumber()
setNationalNumber()
hasNationalNumber()
clearNationalNumber()

public function getNationalNumber(): ?string

Returns the national significant number (without country code or formatting).Returns: string|null - The national number or null if not setExample:

$phoneNumber = $phoneUtil->parse('+44 117 496 0123', null);
echo $phoneNumber->getNationalNumber(); // "1174960123"

public function setNationalNumber(string $value): static

Sets the national number.

value

string

required

The national number (digits only)

Returns: static - The PhoneNumber instanceExample:

$phoneNumber = new \libphonenumber\PhoneNumber();
$phoneNumber->setNationalNumber('1174960123');

public function hasNationalNumber(): bool

Checks if national number is set.Returns: bool - true if set

public function clearNationalNumber(): static

Clears the national number.Returns: static - The PhoneNumber instance

Extension

getExtension()
setExtension()
hasExtension()
clearExtension()

public function getExtension(): ?string

Returns the phone number extension (e.g., “123” from “555-1234 ext. 123”).Returns: string|null - The extension or null if not setExample:

$phoneNumber = $phoneUtil->parse('0117 496 0123 ext. 456', 'GB');
echo $phoneNumber->getExtension(); // "456"

public function setExtension(string $value): static

Sets the extension.

value

string

required

The extension (ASCII digits only)

Returns: static - The PhoneNumber instanceExample:

$phoneNumber->setExtension('123');

public function hasExtension(): bool

Checks if extension is set and non-empty.Returns: bool - true if extension exists

public function clearExtension(): static

Clears the extension.Returns: static - The PhoneNumber instance

Italian Leading Zero

In some countries (notably Italy), fixed-line numbers start with “0” even in international format. This field tracks that leading zero.

isItalianLeadingZero()
setItalianLeadingZero()
hasItalianLeadingZero()
clearItalianLeadingZero()

public function isItalianLeadingZero(): ?bool

Returns whether this number has an Italian leading zero.Returns: bool|null - true if has leading zero, false if not, null if not setExample:

$italianNumber = $phoneUtil->parse('+39 02 1234567', null);
var_dump($italianNumber->isItalianLeadingZero()); // bool(true)

public function setItalianLeadingZero(bool $value): static

Sets the Italian leading zero flag.

value

bool

required

Whether number has leading zero

Returns: static - The PhoneNumber instance

public function hasItalianLeadingZero(): bool

Checks if Italian leading zero flag is set.Returns: bool - true if set

public function clearItalianLeadingZero(): static

Clears the Italian leading zero flag.Returns: static - The PhoneNumber instance

Number of Leading Zeros

getNumberOfLeadingZeros()
setNumberOfLeadingZeros()
hasNumberOfLeadingZeros()
clearNumberOfLeadingZeros()

public function getNumberOfLeadingZeros(): int

Returns the number of leading zeros (defaults to 1 if Italian leading zero is set).Returns: int - Number of leading zeros

public function setNumberOfLeadingZeros(int $value): static

Sets the number of leading zeros.

value

int

required

Number of leading zeros

Returns: static - The PhoneNumber instance

public function hasNumberOfLeadingZeros(): bool

Checks if number of leading zeros is explicitly set.Returns: bool - true if set

public function clearNumberOfLeadingZeros(): static

Clears the number of leading zeros (resets to default of 1).Returns: static - The PhoneNumber instance

Raw Input

When using parseAndKeepRawInput(), the original input string is preserved.

getRawInput()
setRawInput()
hasRawInput()
clearRawInput()

public function getRawInput(): ?string

Returns the raw input string as originally provided.Returns: string|null - The raw input or nullExample:

$phoneNumber = $phoneUtil->parseAndKeepRawInput('1-800-GOOG-411', 'US');
echo $phoneNumber->getRawInput(); // "1-800-GOOG-411"

public function setRawInput(string $value): static

Sets the raw input string.

value

string

required

The raw input

Returns: static - The PhoneNumber instance

public function hasRawInput(): bool

Checks if raw input is set.Returns: bool - true if set

public function clearRawInput(): static

Clears the raw input.Returns: static - The PhoneNumber instance

Country Code Source

Indicates how the country code was determined during parsing.

getCountryCodeSource()
setCountryCodeSource()
hasCountryCodeSource()
clearCountryCodeSource()

public function getCountryCodeSource(): ?CountryCodeSource

Returns how the country code was determined.Returns: CountryCodeSource|null enum with values:

FROM_NUMBER_WITH_PLUS_SIGN - From ’+’ prefix
FROM_NUMBER_WITH_IDD - From international dialing prefix
FROM_NUMBER_WITHOUT_PLUS_SIGN - Matched default region
FROM_DEFAULT_COUNTRY - Used default region
UNSPECIFIED - Not specified

Example:

$phoneNumber = $phoneUtil->parseAndKeepRawInput('+44 117 496 0123', null);
echo $phoneNumber->getCountryCodeSource()->name;
// "FROM_NUMBER_WITH_PLUS_SIGN"

public function setCountryCodeSource(CountryCodeSource $value): static

Sets the country code source.

value

CountryCodeSource

required

The country code source

Returns: static - The PhoneNumber instance

public function hasCountryCodeSource(): bool

Checks if country code source is set (not UNSPECIFIED).Returns: bool - true if set

public function clearCountryCodeSource(): static

Clears the country code source (sets to UNSPECIFIED).Returns: static - The PhoneNumber instance

Preferred Carrier Code

The preferred carrier selection code for domestic dialing in some countries (e.g., Colombia).

getPreferredDomesticCarrierCode()
setPreferredDomesticCarrierCode()
hasPreferredDomesticCarrierCode()
clearPreferredDomesticCarrierCode()

public function getPreferredDomesticCarrierCode(): ?string

Returns the preferred domestic carrier code.Returns: string|null - The carrier code or nullExample:

$arNumber = new \libphonenumber\PhoneNumber();
$arNumber->setCountryCode(54);
$arNumber->setNationalNumber('91234125678');
$arNumber->setPreferredDomesticCarrierCode('19');

echo $arNumber->getPreferredDomesticCarrierCode(); // "19"

public function setPreferredDomesticCarrierCode(string $value): static

Sets the preferred carrier code.

value

string

required

The carrier code

Returns: static - The PhoneNumber instance

public function hasPreferredDomesticCarrierCode(): bool

Checks if carrier code is set.Returns: bool - true if set

public function clearPreferredDomesticCarrierCode(): static

Clears the carrier code.Returns: static - The PhoneNumber instance

Utility Methods

mergeFrom()

Merges information from another PhoneNumber object.

public function mergeFrom(PhoneNumber $other): static

other

PhoneNumber

required

The PhoneNumber to merge from

Returns: static - The PhoneNumber instance Example:

$phoneNumber1 = new \libphonenumber\PhoneNumber();
$phoneNumber1->setCountryCode(44);

$phoneNumber2 = new \libphonenumber\PhoneNumber();
$phoneNumber2->setNationalNumber('1174960123');
$phoneNumber2->setExtension('123');

$phoneNumber1->mergeFrom($phoneNumber2);
// Now phoneNumber1 has country code 44, national number 1174960123, and extension 123

equals()

Checks if two PhoneNumber objects are equal.

public function equals(PhoneNumber $other): bool

other

PhoneNumber

required

The PhoneNumber to compare with

Returns: bool - true if equal Example:

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

var_dump($number1->equals($number2)); // bool(true)

clear()

Clears all fields in the PhoneNumber object.

public function clear(): static

Returns: static - The PhoneNumber instance Example:

$phoneNumber->clear();
// All fields are now null/default

__toString()

Returns a string representation of the phone number.

public function __toString(): string

Returns: string - Human-readable representation Example:

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

echo $phoneNumber;
// "Country Code: 44 National Number: 1174960123 Extension: 456"

Method Chaining Example

All setter methods return the PhoneNumber instance, allowing method chaining:

$phoneNumber = new \libphonenumber\PhoneNumber();
$phoneNumber
    ->setCountryCode(44)
    ->setNationalNumber('1174960123')
    ->setExtension('456');

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
echo $phoneUtil->format($phoneNumber, \libphonenumber\PhoneNumberFormat::INTERNATIONAL);
// "+44 117 496 0123 ext. 456"

Serialization

PhoneNumber objects can be serialized and unserialized:

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

// Serialize
$serialized = serialize($phoneNumber);

// Unserialize
$restored = unserialize($serialized);

var_dump($phoneNumber->equals($restored)); // bool(true)

Core Classes

Formatting

Mapping & Geocoding

Utilities

Overview

Creating PhoneNumber Objects

Recommended: Using PhoneNumberUtil

Manual Creation (Not Recommended)

PhoneNumber Structure

Properties and Methods

Country Code

National Number

Extension

Italian Leading Zero

Number of Leading Zeros

Raw Input

Country Code Source

Preferred Carrier Code

Utility Methods

mergeFrom()

equals()

clear()

__toString()

Method Chaining Example

Serialization

See Also

Build docs developers (and LLMs) love

Core Classes

Formatting

Mapping & Geocoding

Utilities

​Overview

​Creating PhoneNumber Objects

​Recommended: Using PhoneNumberUtil

​Manual Creation (Not Recommended)

​PhoneNumber Structure

​Properties and Methods

​Country Code

​National Number

​Extension

​Italian Leading Zero

​Number of Leading Zeros

​Raw Input

​Country Code Source

​Preferred Carrier Code

​Utility Methods

​mergeFrom()

​equals()

​clear()

​__toString()

​Method Chaining Example

​Serialization

​See Also

Build docs developers (and LLMs) love

Overview

Creating PhoneNumber Objects

Recommended: Using PhoneNumberUtil

Manual Creation (Not Recommended)

PhoneNumber Structure

Properties and Methods

Country Code

National Number

Extension

Italian Leading Zero

Number of Leading Zeros

Raw Input

Country Code Source

Preferred Carrier Code

Utility Methods

mergeFrom()

equals()

clear()

__toString()

Method Chaining Example

Serialization

See Also