README

该软件包为Spiral框架提供了解析、格式化和验证国际电话号码的工具。它集成了强大的、广泛使用的电话号码处理库Google libphonenumber。

要求

确保您的服务器已配置以下PHP版本和扩展

• PHP 8.1+
• Spiral框架 3.5+

安装

要安装此软件包，请使用Composer运行以下命令

composer require zentlix/libphonenumber

要在您的Spiral框架应用程序中启用此软件包，您需要将Spiral\PhoneNumber\Bootloader\PhoneNumberBootloader类添加到应用程序的bootloader列表中

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

注意如果您使用spiral-packages/discoverer，则无需自行注册bootloader。

配置

配置文件应位于app/config/libphonenumber.php，允许您设置电话号码的默认区域和默认格式等选项。

以下是一个配置文件的示例

use libphonenumber\PhoneNumberFormat;
use libphonenumber\PhoneNumberUtil;

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

default_region选项指定了解析和格式化电话号码时使用的默认区域代码。这可以是任何有效的区域代码，例如US、GB等。

default_format选项指定了解析电话号码时使用的默认格式。这可以是libphonenumber\PhoneNumberFormat类提供的任何常量，例如NATIONAL、INTERNATIONAL或E164。

用法

libphonenumber\PhoneNumberUtil类提供了从字符串解析电话号码、将电话号码格式化为字符串和验证电话号码的方法。

libphonenumber\PhoneNumber类是一个表示电话号码的面向对象的类。它是libphonenumber\PhoneNumberUtil类的parse方法返回的，并存储了完整的电话号码信息，如国家代码、国内号码和其他细节。

使用PhoneNumberUtil类的一种方法是通过依赖注入将其注入到您的类中。例如

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');

         // ...
     }
}

或者，您可以通过调用PhoneNumberUtil::getInstance方法手动创建libphonenumber\PhoneNumberUtil实例。例如

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

以下是如何使用libphonenumber\PhoneNumberUtil和libphonenumber\PhoneNumber类提供的一些方法的示例

$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

验证

Symfony验证器

该软件包提供了一种Spiral\PhoneNumber\Validator\Constraints\PhoneNumber约束，可以用于使用spiral-packages/symfony-validator组件验证电话号码。

要使用Spiral\PhoneNumber\Validator\Constraints\PhoneNumber约束，您首先需要确保已安装并启用了spiral-packages/symfony-validator软件包在您的Spiral框架应用程序中。

一旦安装并启用了spiral-packages/symfony-validator软件包，您就可以像这样在代码中使用PhoneNumber约束

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

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

在此示例中，使用属性将PhoneNumber约束应用于User类的$phone属性。这将导致验证器在验证User对象时将$phone属性作为电话号码进行验证。如果$phone属性的值不是有效的电话号码，验证将失败。

您还可以在使用PhoneNumber约束时指定其他选项

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验证器

该软件包提供了一种Spiral\PhoneNumber\Validator\Checker\PhoneNumberChecker检查器，可以用于使用spiral/validator组件验证电话号码。

要使用 Spiral\PhoneNumber\Validator\Checker\PhoneNumberChecker 检查器，您首先需要确保在您的 Spiral Framework 应用程序中已安装并启用了 spiral/validator 包。

一旦安装并启用了 spiral/validator 包，您可以在代码中使用 PhoneNumberChecker 检查器，如下所示

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.']
            ]
        ]);
    }
}

在这个例子中，PhoneNumberChecker 检查器应用于 UserRequest 类的 $phone 属性。这意味着当 UserRequest 对象进行验证时，验证器会将 $phone 属性作为电话号码进行验证。如果 $phone 属性的值不是一个有效的电话号码，验证将失败。

序列化

该包提供了一个 Spiral\PhoneNumber\Serializer\Normalizer\PhoneNumberNormalizer 类，可用于使用 spiral-packages/symfony-serializer 包对 libphonenumber\PhoneNumber 对象进行序列化和反序列化。

一旦安装并启用了 spiral-packages/symfony-serializer 包，PhoneNumberNormalizer 类将自动注册为 libphonenumber\PhoneNumber 对象的序列化器。这意味着您可以使用 Symfony 序列化器对 libphonenumber\PhoneNumber 对象进行序列化和反序列化，就像任何其他对象一样。

$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

该包提供了一个 Spiral\PhoneNumber\Twig\Extension\PhoneNumberExtension 类，可用于向 Twig 模板引擎添加 过滤器 和 测试。

要使用 PhoneNumberExtension 类，您首先需要确保在您的 Spiral Framework 应用程序中已安装并启用了 spiral/twig-bridge 包。

一旦安装并启用了 spiral/twig-bridge 包，PhoneNumberExtension 类将自动注册为 Twig 的扩展。

PhoneNumberExtension 类提供了以下过滤器

• phone_number_format：格式化电话号码，用于国际拨号。
• phone_number_format_out_of_country_calling_number：格式化 `libphonenumber\Phone`

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

测试

composer test

composer psalm

composer cs

变更日志

有关最近更改的更多信息，请参阅 变更日志

许可证

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件