README

PHP的电话号码库。

这个库是对 giggsey/libphonenumber-for-php 的封装，而后者又是 Google的libphonenumber 的移植。

它提供了等价的功能，以下是一些实现上的差异：

• PhoneNumber 是一个不可变类；它可以安全地传递而不用担心它被修改的风险；
• PhoneNumber 不仅仅是一个数据容器，它提供了解析、格式化和验证电话号码的所有方法；它透明地封装了 PhoneNumberUtil；
• PhoneNumberFormat 和 PhoneNumberType 是原生PHP枚举。

安装

这个库可以通过 Composer 安装。

composer require brick/phonenumber

要求

这个库需要PHP 8.1或更高版本。

对于PHP 7.4和PHP 8.0的支持，请使用版本 0.5。对于PHP 7.1的支持，请使用版本 0.4。对于PHP 5.6和PHP 7.0的支持，请使用版本 0.1。请注意，这些PHP版本已经结束支持。如果您还在使用这些PHP版本之一，您应该考虑尽快升级。

项目状态与发布流程

虽然这个库仍在开发中，但它经过了良好的测试，应该足够稳定，可以在生产环境中使用。

当前发布版本编号为 0.x.y。当引入非破坏性更改（添加新方法、优化现有代码等）时，y 会递增。

当引入破坏性更改时，总是开始新的 0.x 版本周期。

因此，将您的项目锁定到给定的发布周期（如 0.6.*）是安全的。

如果您需要升级到新的发布周期，请查看 发布历史，了解每个进一步的 0.x.0 版本引入的更改列表。

快速开始

所有类都位于 Brick\PhoneNumber 命名空间中。

要获取 PhoneNumber 的实例，请使用 parse() 方法

• 使用国际号码： PhoneNumber::parse('+33123456789')；
• 使用国内号码和区号： PhoneNumber::parse('01 23 45 67 89', 'FR')；

验证号码

parse() 方法对号码相当宽容；它基本上尝试匹配区号，并验证该国家的电话号码长度。

如果号码确实格式不正确，它会抛出 PhoneNumberParseException

use Brick\PhoneNumber\PhoneNumber;
use Brick\PhoneNumber\PhoneNumberParseException;

try {
    $number = PhoneNumber::parse('+333');
}
catch (PhoneNumberParseException $e) {
    // 'The string supplied is too short to be a phone number.'
}

在大多数情况下，建议额外进行一步验证，使用 isValidNumber() 或 isPossibleNumber()

if (! $number->isPossibleNumber()) {
    // a more lenient and faster check than `isValidNumber()`
}

if (! $number->isValidNumber()) {
    // strict check relying on up-to-date metadata library
}

以下是一个经验法则：

• 当号码来自用户输入时，进行完整的验证：调用 parse() 并捕获 PhoneNumberParseException，如果没有异常发生，然后调用 isValidNumber()（或对于更宽容的检查，请使用 isPossibleNumber()）；
• 当号码稍后从您的数据库检索，并且之前已经验证过时，您只需执行盲目的 parse()。

格式化号码

基本格式化

您可以使用与 PhoneNumberFormat 枚举值一起使用的 format() 方法。

$number = PhoneNumber::parse('+41446681800');
$number->format(PhoneNumberFormat::E164); // +41446681800
$number->format(PhoneNumberFormat::INTERNATIONAL); // +41 44 668 18 00
$number->format(PhoneNumberFormat::NATIONAL); // 044 668 18 00
$number->format(PhoneNumberFormat::RFC3966); // tel:+41-44-668-18-00

从其他国家拨打电话的格式化

您可能希望向特定国家的观众展示一个电话号码，并在需要时包含正确的国际前缀。这正是 formatForCallingFrom() 方法所做的。

$number = PhoneNumber::parse('+447123456789');
$number->formatForCallingFrom('GB'); // 07123 456789
$number->formatForCallingFrom('FR'); // 00 44 7123 456789
$number->formatForCallingFrom('US'); // 011 44 7123 456789

号码类型

在某些情况下，可以使用 getNumberType() 方法知道电话号码的类型（固定电话、移动电话等），该方法返回一个 PhoneNumberType 枚举值。

PhoneNumber::parse('+336123456789')->getNumberType(); // PhoneNumberType::MOBILE
PhoneNumber::parse('+33123456789')->getNumberType(); // PhoneNumberType::FIXED_LINE

如果类型未知，则返回 PhoneNumberType::UNKNOWN 值。请查看 PhoneNumberType 枚举以获取所有可能的值。

号码信息

您可以从电话号码中提取以下信息

$number = PhoneNumber::parse('+447123456789');
echo $number->getRegionCode(); // GB
echo $number->getCountryCode(); // 44
echo $number->getNationalNumber(); // 7123456789

示例号码

您可以根据国家代码和可选的号码类型（默认为固定电话）获取示例号码。这可以用作输入字段的占位符，例如。

echo PhoneNumber::getExampleNumber('FR'); // +33123456789
echo PhoneNumber::getExampleNumber('FR', PhoneNumberType::MOBILE); // +33612345678

getExampleNumber() 的返回类型是 PhoneNumber 实例，因此您可以按需对其进行格式化。

echo PhoneNumber::getExampleNumber('FR')->formatForCallingFrom('FR'); // 01 23 45 67 89

如果为该国家代码/号码类型组合不可用示例电话号码，则抛出 PhoneNumberException。

转换为字符串

将 PhoneNumber 转换为字符串返回其 E164 表示形式（以加号 + 后跟数字），因此以下内容是等效的：

(string) $phoneNumber

$phoneNumber->format(PhoneNumberFormat::E164)

您可以将 PhoneNumber 序列化为字符串，然后使用 parse() 方法（不带有国家代码）恢复它。

$phoneNumber = PhoneNumber::parse('02079834000', 'GB');
$phoneNumberAsString = (string) $phoneNumber; // +442079834000
$phoneNumber2 = PhoneNumber::parse($phoneNumberAsString);

$phoneNumber2->isEqualTo($phoneNumber); // true

Doctrine 映射

您可以使用 brick/phonenumber-doctrine 包在您的 Doctrine 实体中使用 PhoneNumber 对象。