README

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:

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, 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:

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:

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

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

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

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

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

composer test

composer psalm

composer cs

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

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

zentlix / libphonenumber

Maintainers

Details