PHPackages                             odolbeau/phone-number-bundle - 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. [Utility & Helpers](/categories/utility)
4. /
5. odolbeau/phone-number-bundle

ActiveSymfony-bundle[Utility & Helpers](/categories/utility)

odolbeau/phone-number-bundle
============================

Integrates libphonenumber into your Symfony application

v4.2.5(7mo ago)24910.3M↓10.9%44[3 issues](https://github.com/odolbeau/phone-number-bundle/issues)10MITPHPPHP >=8.1

Since Oct 10Pushed 6mo ago8 watchersCompare

[ Source](https://github.com/odolbeau/phone-number-bundle)[ Packagist](https://packagist.org/packages/odolbeau/phone-number-bundle)[ Docs](https://github.com/odolbeau/phone-number-bundle)[ RSS](/packages/odolbeau-phone-number-bundle/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (10)Dependencies (16)Versions (56)Used By (10)

PhoneNumberBundle
=================

[](#phonenumberbundle)

[![Build Status](https://github.com/odolbeau/phone-number-bundle/actions/workflows/tests.yml/badge.svg)](https://github.com/odolbeau/phone-number-bundle/actions)[![Latest stable version](https://camo.githubusercontent.com/bd887cb198d843a5334eb32445bb0fd943421e0f82d6f960f7d1cc3daf292eae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f646f6c626561752f70686f6e652d6e756d6265722d62756e646c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/odolbeau/phone-number-bundle)[![License](https://camo.githubusercontent.com/1f7aa1cd65e7070990821232df53b277518be262cddf072ec4c2d2fe1f42523c/687474703a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f646f6c626561752f70686f6e652d6e756d6265722d62756e646c652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/odolbeau/phone-number-bundle)

[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)

**This bundle is a fork of [misd-service-development/phone-number-bundle](https://github.com/misd-service-development/phone-number-bundle). As this project doesn't look maintained anymore, we decided to create & maintain a fork.**

This bundle integrates [Google's libphonenumber](https://github.com/googlei18n/libphonenumber) into your Symfony application through the [giggsey/libphonenumber-for-php](https://github.com/giggsey/libphonenumber-for-php) port.

Installation
------------

[](#installation)

1. Use Composer to download the PhoneNumberBundle:

```
composer require odolbeau/phone-number-bundle
```

if you're using Symfony Flex, that's all you have to do! Otherwise:

2. Register the bundle in your application:

```
// app/AppKernel.php

public function registerBundles()
{
    $bundles = [
        // ...
        new Misd\PhoneNumberBundle\MisdPhoneNumberBundle()
    ];
}
```

### Update from `misd/phone-number-bundle`

[](#update-from-misdphone-number-bundle)

The update from `misd/phone-number-bundle` to `odolbeau/phone-number-bundle` should be really easy.

Update your composer.json:

```
-        "misd/phone-number-bundle": "^1.3",
+        "odolbeau/phone-number-bundle": "^4.0",
```

Then run `composer update misd/phone-number-bundle odolbeau/phone-number-bundle`.

If you're using a container parameter or alias defined by `misd/phone-number-bundle` you can use `"odolbeau/phone-number-bundle": "^2.0"` until your project is cleaned.

Usage
-----

[](#usage)

### Services

[](#services)

The following services are available:

ServiceID (Removed in 3.0)libphonenumber version`libphonenumber\PhoneNumberUtil``libphonenumber.phone_number_util``libphonenumber\geocoding\PhoneNumberOfflineGeocoder``libphonenumber.phone_number_offline_geocoder`>=5.8.8`libphonenumber\ShortNumberInfo``libphonenumber.short_number_info`>=5.8`libphonenumber\PhoneNumberToCarrierMapper``libphonenumber.phone_number_to_carrier_mapper`>=5.8.8`libphonenumber\PhoneNumberToTimeZonesMapper``libphonenumber.phone_number_to_time_zones_mapper`>=5.8.8To parse a string into a `libphonenumber\PhoneNumber` object, [inject the service](https://symfony.com/doc/current/service_container.html) and:

```
    $phoneNumber = $this->phoneNumberUtil->parse($string, PhoneNumberUtil::UNKNOWN_REGION);
```

### Doctrine mapping

[](#doctrine-mapping)

*Requires `doctrine/doctrine-bundle`.*

To persist `libphonenumber\PhoneNumber` objects, add the `Misd\PhoneNumberBundle\Doctrine\DBAL\Types\PhoneNumberType` mapping to your application's config:

```
// app/config.yml

doctrine:
    dbal:
        types:
            phone_number: Misd\PhoneNumberBundle\Doctrine\DBAL\Types\PhoneNumberType
```

You can then use the `phone_number` mapping:

```
/**
 * @ORM\Column(type="phone_number")
 */
private $phoneNumber;
```

This creates a `varchar(35)` column with a Doctrine mapping comment.

Note that if you're putting the `phone_number` type on an already-existing schema the current values must be converted to the `libphonenumber\PhoneNumberFormat::E164` format.

### Twig Templating

[](#twig-templating)

If any of the `form_div_layout`, `bootstrap_3_*`, `bootstrap_4_*` or `bootstrap_5_*` layouts are registered in your twig configuration, the bundle will automatically register the template used to render the `Misd\PhoneNumberBundle\Form\Type` form type.

#### phone\_number\_format

[](#phone_number_format)

The `phone_number_format` filter can be used to format a phone number object. A `libphonenumber\PhoneNumberFormat` constant can be passed as argument to specify in which format the number should be printed.

For example, to format an object called `myPhoneNumber` in the `libphonenumber\PhoneNumberFormat::NATIONAL` format:

```
{{ myPhoneNumber|phone_number_format('NATIONAL') }}
{# or #}
{{ myPhoneNumber|phone_number_format(enum('libphonenumber\PhoneNumberFormat').NATIONAL) }}
```

By default phone numbers are formatted in the `libphonenumber\PhoneNumberFormat::INTERNATIONAL` format.

##### phone\_number\_of\_type

[](#phone_number_of_type)

The `phone_number_of_type` test can be used to check a phone number against a type: A `libphonenumber\PhoneNumberType` constant name must be passed to specify to which type a number has to match.

For example, to check if an object called `myPhoneNumber` is a `libphonenumber\PhoneNumberType::MOBILE` type:

```
{% if myPhoneNumber is phone_number_of_type('MOBILE') }} %} ... {% endif %}
```

### Using `libphonenumber\PhoneNumber` objects in forms

[](#using-libphonenumberphonenumber-objects-in-forms)

You can use the `PhoneNumberType` (`phone_number` for Symfony 2.7) form type to create phone number fields. There are two widgets available.

#### Single text field

[](#single-text-field)

A single text field allows the user to type in the complete phone number. When an international prefix is not entered, the number is assumed to be part of the set `default_region`. For example:

```
use libphonenumber\PhoneNumberFormat;
use Misd\PhoneNumberBundle\Form\Type\PhoneNumberType;
use Symfony\Component\Form\FormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder->add('phoneNumber', PhoneNumberType::class, [
        'default_region' => 'GB',
        'format' => PhoneNumberFormat::NATIONAL,
        'number_type' => PhoneNumberType::NUMBER_TYPE_TEL,
    ]);
}
```

By default the `default_region` and `format` options are `PhoneNumberUtil::UNKNOWN_REGION` and `PhoneNumberFormat::INTERNATIONAL` respectively.

#### Country choice fields

[](#country-choice-fields)

The phone number can be split into a country choice and phone number fields. This allows the user to choose the relevant country (from a customisable list) and type in the phone number without international dialling.

```
use libphonenumber\PhoneNumberFormat;
use Misd\PhoneNumberBundle\Form\Type\PhoneNumberType;
use Symfony\Component\Form\FormBuilderInterface;

public function buildForm(FormBuilderInterface $builder, array $options)
{
    $builder->add('phoneNumber', PhoneNumberType::class, [
        'widget' => PhoneNumberType::WIDGET_COUNTRY_CHOICE,
        'number_type' => PhoneNumberType::NUMBER_TYPE_TEL,
        'country_choices' => ['GB', 'JE', 'FR', 'US'],
        'preferred_country_choices' => ['GB', 'JE'],
        'manage_leading_zeros' => true,
    ]);
}
```

This produces the preferred choices of 'Jersey' and 'United Kingdom', and regular choices of 'France' and 'United States'.

The `number_type` option lets you choose how the phone number should be displayed — either as a `tel` or a `text` field.

By default the `country_choices` is empty, which means all countries are included, as is `preferred_country_choices`. The option `country_placeholder` can be specified to create a placeholder option on above the whole list.

The option `manage_leading_zeros` can be specified to manage leading zeros in the phone number. By default, it is set to `false`, which means that leading zeros are not managed. If you set it to `true`, the leading zeros will be removed when the phone number is displayed in the form, and added back when the phone number is submitted. This is useful for countries where leading zeros are not used in the international format, but are used in the national format.

The option `country_display_type` can be specified to change the country dropdown label format. There are two formats available :

display typeResult`display_country_full` (default)United Kingdom (+44)`display_country_short`GB +44And with the option `country_display_emoji_flag` set to `true` (default is `false`) you can add the emoji flag of the country before the label :

display typeResult`display_country_full` (default)🇬🇧 United Kingdom (+44)`display_country_short`🇬🇧 GB +44### Validating phone numbers

[](#validating-phone-numbers)

ℹ️ *Using a Symfony or PHP version that does not support attributes? This bundle also supports validation as annotation. Take a look at the [old documentation](https://github.com/odolbeau/phone-number-bundle/blob/v3.4.2/README.md#validating-phone-numbers).*

You can use the `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber` constraint to make sure that either a `libphonenumber\PhoneNumber` object or a plain string is a valid phone number. For example:

```
use Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber as AssertPhoneNumber;

 #[AssertPhoneNumber()]
private $phoneNumber;
```

You can set the default region through the `defaultRegion` property:

```
use Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber as AssertPhoneNumber;

 #[AssertPhoneNumber(defaultRegion: 'GB')]
private $phoneNumber;
```

You can also set default region in the bundle config:

```
misd_phone_number:
    validator:
        default_region: GB
```

You can also define a region dynamically according to the context of the validated object thanks to the "regionPath" property (here according to the user's region):

```
use Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber as AssertPhoneNumber;

#[AssertPhoneNumber(regionPath: 'countryCode')]
private $phoneNumber;

private $countryCode;

public function getCountryCode()
{
    return $this->countryCode;
}
```

By default, any valid phone number will be accepted. You can restrict the type through the `type` property, recognised values:

- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::ANY` (default)
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::FIXED_LINE`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::MOBILE`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::PAGER`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::PERSONAL_NUMBER`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::PREMIUM_RATE`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::SHARED_COST`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::TOLL_FREE`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::UAN`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::VOIP`
- `Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber::VOICEMAIL`

(Note that libphonenumber cannot always distinguish between mobile and fixed-line numbers (eg in the USA), in which case it will be accepted.)

```
use Misd\PhoneNumberBundle\Validator\Constraints\PhoneNumber as AssertPhoneNumber;

#[AssertPhoneNumber(type: [AssertPhoneNumber::MOBILE])]
private $mobilePhoneNumber;

#[AssertPhoneNumber(type: [AssertPhoneNumber::FIXED_LINE, AssertPhoneNumber::VOIP])]
private $fixedOrVoipPhoneNumber;
```

### Translations

[](#translations)

The bundle contains translations for the form field and validation constraints.

In cases where a language uses multiple terms for mobile phones, the generic language locale will use the term 'mobile', while country-specific locales will use the relevant term. So in English, for example, `en` uses 'mobile', `en_US` uses 'cell' and `en_SG` uses 'handphone'.

If your language doesn't yet have translations, feel free to open a pull request to add them in!

### Configuration

[](#configuration)

To disable integrations with components

```
misd_phone_number:
    twig: false
    form: false
    serializer: false
    validator: false
```

License
-------

[](#license)

This bundle is released under the MIT License. See the bundled LICENSE file for details.

###  Health Score

68

—

FairBetter than 100% of packages

Maintenance66

Regular maintenance activity

Popularity65

Solid adoption and visibility

Community41

Growing community involvement

Maturity85

Battle-tested with a long release history

 Bus Factor2

2 contributors hold 50%+ of commits

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 ~82 days

Recently: every ~16 days

Total

54

Last Release

216d ago

Major Versions

1.3.x-dev → v2.0.02019-11-25

v2.0.2 → v3.0.02019-11-26

v3.10.0 → v4.0.02023-12-06

PHP version history (5 changes)v1.0.0PHP >=5.3.3

v2.0.0PHP ^7.2

v3.3.0PHP >7.2.5

v3.5.0PHP >=7.4

v3.10.0PHP >=8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/4b0aaaa249bfef22b586e459b3fd8687e58644fb6223ffe8e4e709ac05be704d?d=identicon)[OskarStark](/maintainers/OskarStark)

![](https://www.gravatar.com/avatar/d3f32527fbf2e4214a29d86a441db4d130535437cf1911a6b0e6ef13db1c84aa?d=identicon)[jderusse](/maintainers/jderusse)

![](https://avatars.githubusercontent.com/u/132011?v=4)[Nikita (Anatolievich) Dudnik](/maintainers/Nek)[@Nek](https://github.com/Nek)

![](https://www.gravatar.com/avatar/6662493c184b0ed32978349f4162cac376a2e1026c7f3a06cf1a9565867ecf15?d=identicon)[odolbeau](/maintainers/odolbeau)

![](https://www.gravatar.com/avatar/1d6964679a4e930756c0d892aa4267be0f4257f2557141f6635f7a42403e859d?d=identicon)[maxhelias](/maintainers/maxhelias)

---

Top Contributors

[![thewilkybarkid](https://avatars.githubusercontent.com/u/1784740?v=4)](https://github.com/thewilkybarkid "thewilkybarkid (153 commits)")[![Nek-](https://avatars.githubusercontent.com/u/972456?v=4)](https://github.com/Nek- "Nek- (65 commits)")[![maxhelias](https://avatars.githubusercontent.com/u/12966574?v=4)](https://github.com/maxhelias "maxhelias (47 commits)")[![odolbeau](https://avatars.githubusercontent.com/u/680206?v=4)](https://github.com/odolbeau "odolbeau (29 commits)")[![rh389](https://avatars.githubusercontent.com/u/102418547?v=4)](https://github.com/rh389 "rh389 (12 commits)")[![dmaicher](https://avatars.githubusercontent.com/u/921145?v=4)](https://github.com/dmaicher "dmaicher (8 commits)")[![Crovitche-1623](https://avatars.githubusercontent.com/u/35468476?v=4)](https://github.com/Crovitche-1623 "Crovitche-1623 (6 commits)")[![xabbuh](https://avatars.githubusercontent.com/u/1957048?v=4)](https://github.com/xabbuh "xabbuh (6 commits)")[![nicolassing](https://avatars.githubusercontent.com/u/619752?v=4)](https://github.com/nicolassing "nicolassing (6 commits)")[![norkunas](https://avatars.githubusercontent.com/u/2722872?v=4)](https://github.com/norkunas "norkunas (5 commits)")[![robhogan](https://avatars.githubusercontent.com/u/2590098?v=4)](https://github.com/robhogan "robhogan (5 commits)")[![rvanlaak](https://avatars.githubusercontent.com/u/2707563?v=4)](https://github.com/rvanlaak "rvanlaak (5 commits)")[![mbabker](https://avatars.githubusercontent.com/u/368545?v=4)](https://github.com/mbabker "mbabker (4 commits)")[![OskarStark](https://avatars.githubusercontent.com/u/995707?v=4)](https://github.com/OskarStark "OskarStark (3 commits)")[![BoShurik](https://avatars.githubusercontent.com/u/1428848?v=4)](https://github.com/BoShurik "BoShurik (3 commits)")[![ste93cry](https://avatars.githubusercontent.com/u/1770485?v=4)](https://github.com/ste93cry "ste93cry (3 commits)")[![jmsche](https://avatars.githubusercontent.com/u/3929498?v=4)](https://github.com/jmsche "jmsche (3 commits)")[![jongotlin](https://avatars.githubusercontent.com/u/165154?v=4)](https://github.com/jongotlin "jongotlin (3 commits)")[![freezy-sk](https://avatars.githubusercontent.com/u/661637?v=4)](https://github.com/freezy-sk "freezy-sk (3 commits)")[![zavarock](https://avatars.githubusercontent.com/u/34218864?v=4)](https://github.com/zavarock "zavarock (3 commits)")

---

Tags

bundlelibphonenumberphonenumberphone-numbertelephone number

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/odolbeau-phone-number-bundle/health.svg)

```
[![Health](https://phpackages.com/badges/odolbeau-phone-number-bundle/health.svg)](https://phpackages.com/packages/odolbeau-phone-number-bundle)
```

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M651](/packages/sylius-sylius)[symfony/maker-bundle

Symfony Maker helps you create empty commands, controllers, form classes, tests and more so you can forget about writing boilerplate code.

3.4k111.1M568](/packages/symfony-maker-bundle)[pentatrion/vite-bundle

Vite integration for your Symfony app

2755.3M13](/packages/pentatrion-vite-bundle)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[contao/core-bundle

Contao Open Source CMS

1231.6M2.4k](/packages/contao-core-bundle)[netgen/layouts-core

Netgen Layouts enables you to build and manage complex web pages in a simpler way and with less coding. This is the core of Netgen Layouts, its heart and soul.

3689.4k10](/packages/netgen-layouts-core)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)