https://github.com/zentlix/libphonenumber
Integrates Google's phone number handling library into Spiral Framework
https://github.com/zentlix/libphonenumber
libphonenumber phone-number phonenumber spiral-framework
Last synced: 4 months ago
JSON representation
Integrates Google's phone number handling library into Spiral Framework
- Host: GitHub
- URL: https://github.com/zentlix/libphonenumber
- Owner: zentlix
- License: mit
- Created: 2023-01-04T11:25:34.000Z (over 3 years ago)
- Default Branch: 1.x
- Last Pushed: 2023-09-11T10:22:40.000Z (almost 3 years ago)
- Last Synced: 2025-07-20T01:14:24.231Z (11 months ago)
- Topics: libphonenumber, phone-number, phonenumber, spiral-framework
- Language: PHP
- Homepage:
- Size: 38.1 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Google libphonenumber integration package for Spiral Framework
[](https://packagist.org/packages/zentlix/libphonenumber)
[](https://packagist.org/packages/zentlix/libphonenumber)
[](https://github.com/zentlix/libphonenumber/actions)
[](https://github.com/zentlix/libphonenumber/actions)
[](https://codecov.io/gh/zentlix/libphonenumber)
[](https://packagist.org/packages/zentlix/libphonenumber)
[](https://shepherd.dev/github/zentlix/libphonenumber)
[](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
Make sure that your server is configured with following PHP version and extensions:
- PHP 8.1+
- Spiral framework 3.5+
## Installation
To install the package, use Composer by running the following command:
```bash
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:
```php
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
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:
```php
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
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:
```php
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:
```php
$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:
```php
$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
### 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:
```php
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:
```php
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
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:
```php
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
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:
```php
$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
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
```php
{{ phoneNumber | phone_number_format('NATIONAL') }}
```
## Testing
```bash
composer test
```
```bash
composer psalm
```
```bash
composer cs
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.