A phone number library for PHP.
This library is a thin wrapper around giggsey/libphonenumber-for-php, itself a port of Google's libphonenumber.
It provides an equivalent functionality, with the following implementation differences:
PhoneNumberis an immutable class; it can be safely passed around without having to worry about the risk for it to be changed;PhoneNumberis not just a mere data container, but provides all the methods to parse, format and validate phone numbers; it transparently encapsulatesPhoneNumberUtil;PhoneNumberFormatandPhoneNumberTypeare native PHP enums.
This library is installable via Composer:
composer require brick/phonenumberThis library requires PHP 8.1 or later.
For PHP 7.4 and PHP 8.0 support, use version 0.5.
For PHP 7.1 support, use version 0.4.
For PHP 5.6 and PHP 7.0 support, use version 0.1.
Note that these 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 should be stable enough to use in production environments.
The current releases are numbered 0.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 new 0.x version cycle is always started.
It is therefore safe to lock your project to a given release cycle, such as 0.6.*.
If you need to upgrade to a newer release cycle, check the release history for a list of changes introduced by each further 0.x.0 version.
All the classes lie in the Brick\PhoneNumber namespace.
To obtain an instance of PhoneNumber, use the parse() method:
- Using an international number:
PhoneNumber::parse('+33123456789'); - Using a national number and a country code:
PhoneNumber::parse('01 23 45 67 89', 'FR');
The parse() 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 a PhoneNumberParseException:
use Brick\PhoneNumber\PhoneNumber;
use Brick\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 with isValidNumber() or isPossibleNumber():
if (! $number->isPossibleNumber()) {
// a more lenient and faster check than `isValidNumber()`
}
if (! $number->isValidNumber()) {
// strict check relying on up-to-date metadata library
}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 blind
parse().
You can use format() with a PhoneNumberFormat 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-00You may want to present a phone number to an audience in a specific country, with the correct international
prefix when required. This is what formatForCallingFrom() does:
$number = PhoneNumber::parse('+447123456789');
$number->formatForCallingFrom('GB'); // 07123 456789
$number->formatForCallingFrom('FR'); // 00 44 7123 456789
$number->formatForCallingFrom('US'); // 011 44 7123 456789In certain cases, it is possible to know the type of a phone number (fixed line, mobile phone, etc.), using
the getNumberType() method, which returns a PhoneNumberType enum value:
PhoneNumber::parse('+336123456789')->getNumberType(); // PhoneNumberType::MOBILE
PhoneNumber::parse('+33123456789')->getNumberType(); // PhoneNumberType::FIXED_LINEIf the type is unknown, the PhoneNumberType::UNKNOWN value is returned.
Check the PhoneNumberType enum for all possible values.
You can extract the following information from a phone number:
$number = PhoneNumber::parse('+447123456789');
echo $number->getRegionCode(); // GB
echo $number->getCountryCode(); // 44
echo $number->getNationalNumber(); // 7123456789You 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'); // +33123456789
echo PhoneNumber::getExampleNumber('FR', PhoneNumberType::MOBILE); // +33612345678The return type of getExampleNumber() is a PhoneNumber instance, so you can format it as you like:
echo PhoneNumber::getExampleNumber('FR')->formatForCallingFrom('FR'); // 01 23 45 67 89If no example phone number is available for the country code / number type combination, a PhoneNumberException is thrown.
Casting a PhoneNumber to string returns its E164 representation (+ followed by digits), so the following are equivalent:
(string) $phoneNumber$phoneNumber->format(PhoneNumberFormat::E164)You can serialize a PhoneNumber to string, then recover it using parse() without a country code:
$phoneNumber = PhoneNumber::parse('02079834000', 'GB');
$phoneNumberAsString = (string) $phoneNumber; // +442079834000
$phoneNumber2 = PhoneNumber::parse($phoneNumberAsString);
$phoneNumber2->isEqualTo($phoneNumber); // trueYou can use PhoneNumber objects in your Doctrine entities using the brick/phonenumber-doctrine package.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent