Repository files navigation

A phone number library for PHP.

This library is a thin wrapper aroundgiggsey/libphonenumber-for-php,itself a port ofGoogle's libphonenumber.

It provides an equivalent functionality, with the following implementation differences:

• PhoneNumber is an immutable class; it can be safely passed around without having to worry about the risk for it to be changed;
• PhoneNumber is not just a mere data container, but provides all the methods to parse, format and validate phone numbers; it transparently encapsulates services such asPhoneNumberUtil;

This library is installable viaComposer:

composer require brick/phonenumber

This library requires PHP 8.1 or later.

For PHP 7.4 and PHP 8.0 support, use version0.5.For PHP 7.1 support, use version0.4.For PHP 5.6 and PHP 7.0 support, use version0.1.Note thatthese PHP versions are EOL and not supported anymore. If you're still using one of these PHP versions, you should consider upgrading as soon as possible.

While this library is still under development, it is well tested and is considered stable enough to use in production environments.

The current releases are numbered0.x.y. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.),y is incremented.

When a breaking change is introduced, a new0.x version cycle is always started.

It is therefore safe to lock your project to a given release cycle, such as0.7.*.

If you need to upgrade to a newer release cycle, check therelease history for a list of changes introduced by each further0.x.0 version.

All the classes lie in theBrick\PhoneNumber namespace.

To obtain an instance ofPhoneNumber, use theparse() method:

• Using an international number:PhoneNumber::parse('+33123456789');
• Using a national number and a country code:PhoneNumber::parse('01 23 45 67 89', 'FR');

Theparse() method is quite permissive with numbers; it basically attempts to match a country code,and validates the length of the phone number for this country.

If a number is really malformed, it throws aPhoneNumberParseException:

useBrick\PhoneNumber\PhoneNumber;useBrick\PhoneNumber\PhoneNumberParseException;try {$number = PhoneNumber::parse('+333');}catch (PhoneNumberParseException$e) {// 'The string supplied is too short to be a phone number.'}

In most cases, it is recommended to perform an extra step of validation withisValidNumber() orisPossibleNumber():

if ($number->isValidNumber()) {// strict check relying on up-to-date metadata library}// orif ($number->isPossibleNumber()) {// a more lenient and faster check than `isValidNumber()`}

As a rule of thumb, do the following:

• When the number comes from user input, do a full validation:parse() and catchPhoneNumberParseException, then callisValidNumber() (orisPossibleNumber() for a more lenient check) if no exception occurred;
• When the number is later retrieved from your database, and has been validated before, you can just perform a blindparse().

You can useformat() with aPhoneNumberFormat enum value:

$number = PhoneNumber::parse('+41446681800');$number->format(PhoneNumberFormat::E164);// +41446681800$number->format(PhoneNumberFormat::INTERNATIONAL);// +41 44 668 18 00$number->format(PhoneNumberFormat::NATIONAL);// 044 668 18 00$number->format(PhoneNumberFormat::RFC3966);// tel:+41-44-668-18-00

You may want to present a phone number to an audience in a specific country, with the correct internationalprefix when required. This is whatformatForCallingFrom() does:

$number = PhoneNumber::parse('+447123456789');$number->formatForCallingFrom('GB');// 07123 456789$number->formatForCallingFrom('FR');// 00 44 7123 456789$number->formatForCallingFrom('US');// 011 44 7123 456789

If you want to present a number to dial from a mobile phone, you can useformatForMobileDialing():

$number = PhoneNumber::parse('+447123456789');$number->formatForMobileDialing('GB', withFormatting:false);// 07123456789$number->formatForMobileDialing('GB', withFormatting:true);// 07123 456789$number->formatForMobileDialing('FR', withFormatting:false);// +447123456789$number->formatForMobileDialing('FR', withFormatting:true);// +44 7123 456789

You can extract basic information from a phone number:

$number = PhoneNumber::parse('+447123456789');$number->getRegionCode();// GB$number->getCountryCode();// 44$number->getNationalNumber();// 7123456789

In certain cases, it is possible to know the type of a phone number (fixed line, mobile phone, etc.), usingthegetNumberType() method, which returns aPhoneNumberType enum value:

PhoneNumber::parse('+336123456789')->getNumberType();// PhoneNumberType::MOBILEPhoneNumber::parse('+33123456789')->getNumberType();// PhoneNumberType::FIXED_LINE

If the type is unknown, thePhoneNumberType::UNKNOWN value is returned.Check thePhoneNumberType enum for all possible values.

You can get a human-readable description of a phone number:

PhoneNumber::parse('+33123456789')->getDescription(locale:'en');// FrancePhoneNumber::parse('+16509030000')->getDescription(locale:'en');// Mountain View, CA

For some phone numbers, it is possible to get the carrier name:

$number = PhoneNumber::parse('+336789012345');$number->getCarrierName(languageCode:'en');// Orange France

Note that in countries that support mobile number portability, the carrier name for a phone number may no longer becorrect. You can control whether the carrier name should be returned in this case, by passing aCarrierNameMode enum:

// null, because France supports mobile number portability$number->getCarrierName(languageCode:'en', mode: CarrierNameMode::MOBILE_NO_PORTABILITY_ONLY);

You can get the time zones that typically match a phone number:

$number = PhoneNumber::parse('+14155552671');$number->getTimeZones();// ['America/Los_Angeles']

You can get an example number for a country code and an optional number type (defaults to fixed line).This can be useful to use as a placeholder in an input field, for example:

echo PhoneNumber::getExampleNumber('FR');// +33123456789echo PhoneNumber::getExampleNumber('FR', PhoneNumberType::MOBILE);// +33612345678

The return type ofgetExampleNumber() is aPhoneNumber instance, so you can format it as you like:

echo PhoneNumber::getExampleNumber('FR')->formatForCallingFrom('FR');// 01 23 45 67 89

If no example phone number is available for the country code / number type combination, aPhoneNumberException is thrown.

Casting aPhoneNumber to string returns its E164 representation (+ followed by digits), so the following are equivalent:

(string)$phoneNumber

$phoneNumber->format(PhoneNumberFormat::E164)

You can serialize aPhoneNumber to string, then recover it usingparse() without a country code:

$phoneNumber = PhoneNumber::parse('02079834000','GB');$phoneNumberAsString = (string)$phoneNumber;// +442079834000$phoneNumber2 = PhoneNumber::parse($phoneNumberAsString);$phoneNumber2->isEqualTo($phoneNumber);// true

You can usePhoneNumber objects in your Doctrine entities using thebrick/phonenumber-doctrine package.