PHPackages brick/phonenumber - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. brick/phonenumber ActiveLibrary brick/phonenumber ================= Phone number library 0.8.0(1y ago)4347.1M↓15.9%3920MITPHPPHP ^8.1CI passing Since Apr 5Pushed 2mo ago11 watchersCompare [ Source](https://github.com/brick/phonenumber)[ Packagist](https://packagist.org/packages/brick/phonenumber)[ GitHub Sponsors](https://github.com/BenMorel)[ RSS](/packages/brick-phonenumber/feed)WikiDiscussions main Synced 1mo ago READMEChangelog (10)Dependencies (4)Versions (15)Used By (20) Brick\\PhoneNumber ================== [](#brickphonenumber) [![](https://raw.githubusercontent.com/brick/brick/master/logo.png)](https://raw.githubusercontent.com/brick/brick/master/logo.png) A phone number library for PHP. [![Build Status](https://github.com/brick/phonenumber/workflows/CI/badge.svg)](https://github.com/brick/phonenumber/actions)[![Coverage Status](https://camo.githubusercontent.com/e4a1d13bc3856b8ef0fe7b370b84d82984aa22fbd14ba071d6234d9269be985c/68747470733a2f2f636f6465636f762e696f2f6769746875622f627269636b2f70686f6e656e756d6265722f67726170682f62616467652e737667)](https://codecov.io/github/brick/phonenumber)[![Latest Stable Version](https://camo.githubusercontent.com/a4380aaedf558092862ea1f8c9606752b8dd74dca41d01f2bf118f0ec42d4290/68747470733a2f2f706f7365722e707567782e6f72672f627269636b2f70686f6e656e756d6265722f762f737461626c65)](https://packagist.org/packages/brick/phonenumber)[![Total Downloads](https://camo.githubusercontent.com/9f0035b61248df635b719c7fc34cb332ad83d420633408832a7f31bc452340d6/68747470733a2f2f706f7365722e707567782e6f72672f627269636b2f70686f6e656e756d6265722f646f776e6c6f616473)](https://packagist.org/packages/brick/phonenumber)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](http://opensource.org/licenses/MIT) This library is a thin wrapper around [giggsey/libphonenumber-for-php](https://github.com/giggsey/libphonenumber-for-php), itself a port of [Google's libphonenumber](https://github.com/googlei18n/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 as `PhoneNumberUtil`; Installation ------------ [](#installation) This library is installable via [Composer](https://getcomposer.org/): ``` composer require brick/phonenumber ``` Requirements ------------ [](#requirements) This 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](http://php.net/supported-versions.php) and not supported anymore. If you're still using one of these PHP versions, you should consider upgrading as soon as possible. Project status & release process ------------------------------------ [](#project-status--release-process) 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 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.8.*`. If you need to upgrade to a newer release cycle, check the [release history](https://github.com/brick/phonenumber/releases) for a list of changes introduced by each further `0.x.0` version. Quick start ----------- [](#quick-start) 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')`; ### Validating a number [](#validating-a-number) 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->isValidNumber()) { // strict check relying on up-to-date metadata library } // or if ($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 catch `PhoneNumberParseException`, then call `isValidNumber()` (or `isPossibleNumber()` 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()`. ### Formatting a number [](#formatting-a-number) #### Basic formatting [](#basic-formatting) You can use `format()` with a [PhoneNumberFormat](https://github.com/brick/phonenumber/blob/master/src/PhoneNumberFormat.php) 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 ``` #### Formatting to call from a given country [](#formatting-to-call-from-a-given-country) You 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 456789 ``` #### Formatting to call from a mobile phone in a given country [](#formatting-to-call-from-a-mobile-phone-in-a-given-country) If you want to present a number to dial from a mobile phone, you can use `formatForMobileDialing()`: ``` $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 ``` ### Getting number information [](#getting-number-information) You can extract basic information from a phone number: ``` $number = PhoneNumber::parse('+447123456789'); $number->getRegionCode(); // GB $number->getCountryCode(); // 44 $number->getNationalNumber(); // 7123456789 ``` #### Number type [](#number-type) In 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](https://github.com/brick/phonenumber/blob/master/src/PhoneNumberType.php) enum value: ``` PhoneNumber::parse('+336123456789')->getNumberType(); // PhoneNumberType::MOBILE PhoneNumber::parse('+33123456789')->getNumberType(); // PhoneNumberType::FIXED_LINE ``` If the type is unknown, the `PhoneNumberType::UNKNOWN` value is returned. Check the `PhoneNumberType` enum for all possible values. #### Description [](#description) You can get a human-readable description of a phone number: ``` PhoneNumber::parse('+33123456789')->getDescription(locale: 'en'); // France PhoneNumber::parse('+16509030000')->getDescription(locale: 'en'); // Mountain View, CA ``` #### Carrier name [](#carrier-name) 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 be correct. You can control whether the carrier name should be returned in this case, by passing a [CarrierNameMode](https://github.com/brick/phonenumber/blob/master/src/CarrierNameMode.php) enum: ``` // null, because France supports mobile number portability $number->getCarrierName(languageCode: 'en', mode: CarrierNameMode::MOBILE_NO_PORTABILITY_ONLY); ``` #### Time zones [](#time-zones) You can get the time zones that typically match a phone number: ``` $number = PhoneNumber::parse('+14155552671'); $number->getTimeZones(); // ['America/Los_Angeles'] ``` ### Example numbers [](#example-numbers) 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'); // +33123456789 echo PhoneNumber::getExampleNumber('FR', PhoneNumberType::MOBILE); // +33612345678 ``` The 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 89 ``` If no example phone number is available for the country code / number type combination, a `PhoneNumberException` is thrown. ### Casting to string [](#casting-to-string) 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); // true ``` ### Doctrine mappings [](#doctrine-mappings) You can use `PhoneNumber` objects in your Doctrine entities using the [brick/phonenumber-doctrine](https://github.com/brick/phonenumber-doctrine) package. ### Health Score 63 — FairBetter than 99% of packages Maintenance69 Regular maintenance activity Popularity65 Solid adoption and visibility Community35 Small or concentrated contributor base Maturity69 Established project with proven stability Bus Factor1 Top contributor holds 95.9% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~264 days Recently: every ~189 days Total 12 Last Release 424d ago PHP version history (5 changes)0.1.0PHP >=5.6 0.2.0PHP >=7.1 0.3.0PHP ^7.1 || ^8.0 0.5.0PHP ^7.4 || ^8.0 v0.6.x-devPHP ^8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/57189121968030f0770811b461cc92f9c19c08f5c4767292f2ede48b7277cfad?d=identicon)[BenMorel](/maintainers/BenMorel) --- Top Contributors [![BenMorel](https://avatars.githubusercontent.com/u/1952838?v=4)](https://github.com/BenMorel "BenMorel (142 commits)")[![andrew-demb](https://avatars.githubusercontent.com/u/12499813?v=4)](https://github.com/andrew-demb "andrew-demb (2 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (1 commits)")[![JohJohan](https://avatars.githubusercontent.com/u/7591464?v=4)](https://github.com/JohJohan "JohJohan (1 commits)")[![svenluijten](https://avatars.githubusercontent.com/u/11269635?v=4)](https://github.com/svenluijten "svenluijten (1 commits)")[![xificurk](https://avatars.githubusercontent.com/u/117465?v=4)](https://github.com/xificurk "xificurk (1 commits)") --- Tags libphonenumberphone-numberphpbrickphonephonenumberphone-number ### Code Quality TestsPHPUnit Static AnalysisPsalm Type Coverage Yes ### Embed Badge ![Health badge](/badges/brick-phonenumber/health.svg) ``` [![Health](https://phpackages.com/badges/brick-phonenumber/health.svg)](https://phpackages.com/packages/brick-phonenumber) ``` ### Alternatives [odolbeau/phone-number-bundle Integrates libphonenumber into your Symfony application 24910.3M11](/packages/odolbeau-phone-number-bundle)[ronanguilloux/isocodes PHP library - Validators for standards from ISO, International Finance, Public Administrations, GS1, Book and Music Industries, Phone numbers & Zipcodes for many countries 8013.3M23](/packages/ronanguilloux-isocodes)[andr-04/jquery.inputmask-multi Inputmask Multi is a plugin which allows to select a mask of input basing on the beginning of entered data (such as an international phone number) 25410.0k](/packages/andr-04-jqueryinputmask-multi)[log1x/acf-phone-number A real ACF phone number field. 12072.5k](/packages/log1x-acf-phone-number)[udokmeci/yii2-phone-validator Modern Yii2 Phone validator wrapper on top of PhoneNumberUtil library also used by Android devices 36218.9k1](/packages/udokmeci-yii2-phone-validator)[rynpsc/craft-phone-number International phone number field. 2265.9k](/packages/rynpsc-craft-phone-number) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)