PHPackages                             zentlix/libphonenumber - 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. zentlix/libphonenumber

ActiveLibrary[Utility & Helpers](/categories/utility)

zentlix/libphonenumber
======================

Integrates Google's phone number handling library into Spiral Framework

v1.2.0(2y ago)1602[1 PRs](https://github.com/zentlix/libphonenumber/pulls)MITPHPPHP ^8.1

Since Jan 8Pushed 2y ago1 watchersCompare

[ Source](https://github.com/zentlix/libphonenumber)[ Packagist](https://packagist.org/packages/zentlix/libphonenumber)[ Docs](https://github.com/zentlix/libphonenumber)[ RSS](/packages/zentlix-libphonenumber/feed)WikiDiscussions 1.x Synced 1mo ago

READMEChangelog (3)Dependencies (18)Versions (5)Used By (0)

Google libphonenumber integration package for Spiral Framework
==============================================================

[](#google-libphonenumber-integration-package-for-spiral-framework)

[![PHP Version Require](https://camo.githubusercontent.com/932190dbc85c72d1a3739a7ba70aff138d58dad08f64109dafc40f6057247d88/68747470733a2f2f706f7365722e707567782e6f72672f7a656e746c69782f6c696270686f6e656e756d6265722f726571756972652f706870)](https://packagist.org/packages/zentlix/libphonenumber)[![Latest Stable Version](https://camo.githubusercontent.com/26c08976e456ee589930211c5ec431b09787944951c8e8c91510ce2e6d10bd33/68747470733a2f2f706f7365722e707567782e6f72672f7a656e746c69782f6c696270686f6e656e756d6265722f762f737461626c65)](https://packagist.org/packages/zentlix/libphonenumber)[![phpunit](https://github.com/zentlix/libphonenumber/actions/workflows/phpunit.yml/badge.svg)](https://github.com/zentlix/libphonenumber/actions)[![psalm](https://github.com/zentlix/libphonenumber/actions/workflows/psalm.yml/badge.svg)](https://github.com/zentlix/libphonenumber/actions)[![Codecov](https://camo.githubusercontent.com/587ed709a8831a60a4c20b381de45b0da8d648a4b270b67cdbe8e67a36eabf72/68747470733a2f2f636f6465636f762e696f2f67682f7a656e746c69782f6c696270686f6e656e756d6265722f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/zentlix/libphonenumber)[![Total Downloads](https://camo.githubusercontent.com/a9ec6d091dbf5212e59e7afc40f236d74118169df2696088c42a6df74b2dd023/68747470733a2f2f706f7365722e707567782e6f72672f7a656e746c69782f6c696270686f6e656e756d6265722f646f776e6c6f616473)](https://packagist.org/packages/zentlix/libphonenumber)[![type-coverage](https://camo.githubusercontent.com/26f91c3651a251e11dcbe790059e578b4632ee34bdb7d5c0a92ed0bc3a1e1ba3/68747470733a2f2f73686570686572642e6465762f6769746875622f7a656e746c69782f6c696270686f6e656e756d6265722f636f7665726167652e737667)](https://shepherd.dev/github/zentlix/libphonenumber)[![psalm-level](https://camo.githubusercontent.com/37125396cd53e2cd19bb21dcb8bd71ca3e32023fb7e1d44f3df3baf19b78f455/68747470733a2f2f73686570686572642e6465762f6769746875622f7a656e746c69782f6c696270686f6e656e756d6265722f6c6576656c2e737667)](https://shepherd.dev/github/zentlix/libphonenumber)

The package provides tools for parsing, formatting, and validating international phone numbers in `Spiral Framework`. It integrates the `Google libphonenumber` library, which is a powerful and widely used library for working with phone numbers.

Requirements
------------

[](#requirements)

Make sure that your server is configured with following PHP version and extensions:

- PHP 8.1+
- Spiral framework 3.5+

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

[](#installation)

To install the package, use Composer by running the following command:

```
composer require zentlix/libphonenumber
```

To enable the package in your Spiral Framework application, you will need to add the `Spiral\PhoneNumber\Bootloader\PhoneNumberBootloader` class to the list of bootloaders in your application:

```
protected const LOAD = [
    // ...
    \Spiral\PhoneNumber\Bootloader\PhoneNumberBootloader::class,
];
```

> **Note**If you are using [`spiral-packages/discoverer`](https://github.com/spiral-packages/discoverer), you don't need to register bootloader by yourself.

Configuration
-------------

[](#configuration)

The configuration file should be located at `app/config/libphonenumber.php`, and it allows you to set options such as the default region and default format for phone numbers.

Here is an example of how the configuration file might look:

```
use libphonenumber\PhoneNumberFormat;
use libphonenumber\PhoneNumberUtil;

return [
    'default_region' => PhoneNumberUtil::UNKNOWN_REGION,
    'default_format' => PhoneNumberFormat::E164,
];
```

The `default_region` option specifies the default region code to use when parsing and formatting phone numbers. This can be set to any valid region code, such as `US`, `GB`, and others.

The `default_format` option specifies the default format to use when formatting phone numbers. This can be set to any of the constants provided by the `libphonenumber\PhoneNumberFormat` class, such as `NATIONAL`, `INTERNATIONAL`, or `E164`.

Usage
-----

[](#usage)

The `libphonenumber\PhoneNumberUtil` class provides methods for parsing phone numbers from strings, formatting phone numbers as strings, and validating phone numbers.

The `libphonenumber\PhoneNumber` class is a class that represents a phone number in an object-oriented format. It is returned by the `parse` method of the `libphonenumber\PhoneNumberUtil` class, and it stores complete phone number information such as the country code, national number, and other details.

One way to use the `PhoneNumberUtil` class is to inject it into your classes using dependency injection. For example:

```
use libphonenumber\PhoneNumberUtil;

final class SomeService
{
     public function __construct(
         private readonly PhoneNumberUtil $phoneNumberUtil
     ) {
     }

     public function do(): void
     {
         $phoneNumber = $this->phoneNumberUtil->parse('+1 650 253 0000', 'US');

         // ...
     }
}
```

Alternatively, you can create a `libphonenumber\PhoneNumberUtil` instance manually by calling the `PhoneNumberUtil::getInstance` method. For example:

```
$utils = PhoneNumberUtil::getInstance();
$phoneNumber = $utils->parse('+1 650 253 0000', 'US');
```

Here is an example of how you might use some of the methods provided by the `libphonenumber\PhoneNumberUtil` and `libphonenumber\PhoneNumber` classes:

```
$utils = libphonenumber\PhoneNumberUtil::getInstance();

$phoneNumber = $utils->parse('+1 650 253 0000', 'US');
$phoneNumber->getCountryCode(); // 1
$phoneNumber->getNationalNumber(); // 6502530000

$utils->format($phoneNumber, PhoneNumberFormat::E164); // +16502530000
$utils->format($phoneNumber, PhoneNumberFormat::INTERNATIONAL); // +1 650-253-0000
$utils->format($phoneNumber, PhoneNumberFormat::NATIONAL); // (650) 253-0000
$utils->format($phoneNumber, PhoneNumberFormat::RFC3966); // tel:+1-650-253-0000
```

Validation
----------

[](#validation)

### Symfony Validator

[](#symfony-validator)

The package provides a `Spiral\PhoneNumber\Validator\Constraints\PhoneNumber` constraint that can be used to validate phone numbers using the `spiral-packages/symfony-validator` component.

To use the `Spiral\PhoneNumber\Validator\Constraints\PhoneNumber` constraint, you will first need to make sure that the `spiral-packages/symfony-validator` package is installed and enabled in your Spiral Framework application.

Once the `spiral-packages/symfony-validator` package is installed and enabled, you can use the `PhoneNumber`constraint in your code like this:

```
use libphonenumber\PhoneNumber;
use Spiral\PhoneNumber\Validator\Constraints;

class User
{
    #[Constraints\PhoneNumber]
    protected ?PhoneNumber $phone = null;
}
```

In this example, the `PhoneNumber` constraint is applied to the **$phone** property of the **User** class using the attribute. This will cause the Validator to validate the **$phone** property as a phone number when the User object is validated. If the value of the $phone property is not a valid phone number, the validation will fail.

You can also specify additional options when using the `PhoneNumber` constraint:

```
use libphonenumber\PhoneNumber;
use libphonenumber\PhoneNumberFormat;
use Spiral\PhoneNumber\Validator\Constraints;

class User
{
    #[Constraints\PhoneNumber(
        format: PhoneNumberFormat::INTERNATIONAL,
        defaultRegion: 'US',
        message: 'The phone number is invalid!'
    )]
    protected ?PhoneNumber $phone = null;
}
```

### Spiral Validator

[](#spiral-validator)

The package provides a `Spiral\PhoneNumber\Validator\Checker\PhoneNumberChecker` checker that can be used to validate phone numbers using the `spiral/validator` component.

To use the `Spiral\PhoneNumber\Validator\Checker\PhoneNumberChecker` checker, you will first need to make sure that the `spiral/validator` package is installed and enabled in your Spiral Framework application.

Once the `spiral/validator` package is installed and enabled, you can use the `PhoneNumberChecker`checker in your code like this:

```
namespace App\Request;

use Spiral\Filters\Attribute\Input\Post;
use Spiral\Filters\Model\Filter;
use Spiral\Filters\Model\FilterDefinitionInterface;
use Spiral\Filters\Model\HasFilterDefinition;
use Spiral\Validator\FilterDefinition;

final class UserRequest extends Filter implements HasFilterDefinition
{
    #[Post]
    public string $phone;

    public function filterDefinition(): FilterDefinitionInterface
    {
        return new FilterDefinition([
            'phone' => ['phone'],
            // or with custom error message
            'phone' => [
                ['phone', 'error' => 'Custom error message.']
            ]
        ]);
    }
}
```

In this example, the `PhoneNumberChecker` checker is applied to the **$phone** property of the **UserRequest** class. This will cause the Validator to validate the **$phone** property as a phone number when the UserRequest object is validated. If the value of the $phone property is not a valid phone number, the validation will fail.

Serialization
-------------

[](#serialization)

The package provides a `Spiral\PhoneNumber\Serializer\Normalizer\PhoneNumberNormalizer` class that can be used to serialize and deserialize `libphonenumber\PhoneNumber` objects using the `spiral-packages/symfony-serializer` package.

Once the `spiral-packages/symfony-serializer` package is installed and enabled, the `PhoneNumberNormalizer` class will be automatically registered as a normalizer for `libphonenumber\PhoneNumber` objects. This means that you can use the Symfony Serializer to serialize and deserialize `libphonenumber\PhoneNumber`objects just like any other object:

```
$utils = \libphonenumber\PhoneNumberUtil::getInstance();

/** @var \Spiral\Serializer\SerializerManager $manager */
$manager = $this->getContainer()->get(\Spiral\Serializer\SerializerManager::class);

$result = $manager->getSerializer('json')->serialize($utils->parse('+1 650 253 0000', 'US'));

echo $result; // "+16502530000"

$phoneNumber = $manager->getSerializer('json')->unserialize(json_encode('+16502530000'), PhoneNumber::class);

var_dump(get_debug_type($phoneNumber)); // libphonenumber\PhoneNumber
```

Twig
----

[](#twig)

The package provides a `Spiral\PhoneNumber\Twig\Extension\PhoneNumberExtension` class that can be used to add `filters` and `test` to the Twig templating engine.

To use the `PhoneNumberExtension` class, you will first need to make sure that the `spiral/twig-bridge` package is installed and enabled in your Spiral Framework application.

Once the `spiral/twig-bridge` package is installed and enabled, the `PhoneNumberExtension` class will be automatically registered as an extension for Twig.

The PhoneNumberExtension class provides the following filters:

- `phone_number_format`: Formats a phone number for out-of-country dialing purposes.
- `phone_number_format_out_of_country_calling_number` : Formats a `libphonenumber\\Phone

```
{{ phoneNumber | phone_number_format('NATIONAL') }}
```

Testing
-------

[](#testing)

```
composer test
```

```
composer psalm
```

```
composer cs
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE) for more information.

###  Health Score

28

—

LowBetter than 54% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity15

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity57

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~56 days

Total

4

Last Release

1051d ago

### Community

Maintainers

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

---

Top Contributors

[![msmakouz](https://avatars.githubusercontent.com/u/67324318?v=4)](https://github.com/msmakouz "msmakouz (9 commits)")

---

Tags

libphonenumberphone-numberphonenumberspiral-frameworklibphonenumberphonenumberphone-numbertelephone numberspiral

###  Code Quality

TestsPHPUnit

Static AnalysisPsalm

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/zentlix-libphonenumber/health.svg)

```
[![Health](https://phpackages.com/badges/zentlix-libphonenumber/health.svg)](https://phpackages.com/packages/zentlix-libphonenumber)
```

###  Alternatives

[odolbeau/phone-number-bundle

Integrates libphonenumber into your Symfony application

24910.3M11](/packages/odolbeau-phone-number-bundle)[log1x/acf-phone-number

A real ACF phone number field.

12072.5k](/packages/log1x-acf-phone-number)[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)