README

是什么？

这是一个用于解析、格式化、存储和验证国际电话号码的PHP库。这个库基于Google的libphonenumber。

• 安装
• 文档
• 在线演示
• 功能亮点
  • 版本控制
  • 快速示例
    • 地理编码器
    • 短号信息
    • 将电话号码映射到运营商
    • 将电话号码映射到时区
• 常见问题解答
  • 无效号码的问题？
• 生成数据
• 与框架集成

安装

当前支持PHP版本 5.3 到 PHP 8.3。

需要PECL mbstring 扩展。

建议使用composer 安装库。

$ composer require giggsey/libphonenumber-for-php

您也可以使用任何其他PSR-4 兼容的自动加载器。

如果您不使用composer，请确保您还加载了这个项目所需的任何依赖，例如 giggsey/locale。

giggsey/libphonenumber-for-php-lite

如果您只想使用核心PhoneNumber Util功能，您可以使用giggsey/libphonenumber-for-php-lite，它提供了更小的包大小。

文档

• PhoneNumber Util
• 短号信息
• 电话号码地理位置
• 电话号码到运营商映射
• 电话号码到时区映射
• 电话号码匹配器
• 键入时格式化

在线演示

提供了在线演示，源代码可在giggsey/libphonenumber-example找到。

功能亮点

• 为世界上所有国家和地区的电话号码进行解析/格式化/验证。
• getNumberType - 根据号码本身获取号码类型；能够区分固定电话、移动电话、免付费电话、付费电话、共享成本、VoIP和个人号码（在可行的情况下）。
• isNumberMatch - 获取两个号码可能相同的置信度。
• getExampleNumber/getExampleNumberByType - 为所有国家和地区的所有电话号码提供有效示例，可以选择需要哪种类型的示例电话号码。
• isValidNumber - 使用长度和前缀信息对区域内的电话号码进行完全验证。
• PhoneNumberOfflineGeocoder - 提供与电话号码相关的地理信息。
• PhoneNumberToTimeZonesMapper - 提供与电话号码相关的时区信息。
• PhoneNumberToCarrierMapper - 提供与电话号码相关的运营商信息。

版本控制

该库将尝试遵循与Google相同的版本号。如果需要，可能会进行额外的发布以修复无法等待Google下一个版本发布的关键问题。

这意味着该项目可能不遵循语义版本控制，而是遵循Google的版本策略。因此，主要版本的跳跃可能实际上不包含任何不兼容的更改。请阅读此类发布的发行说明。

Google试图根据其版本指南中的规定来发布其版本。

快速示例

假设你有一个代表瑞士电话号码的字符串。这是你如何将其解析/归一化到PhoneNumber对象中的方法

$swissNumberStr = "044 668 18 00";
$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
try {
    $swissNumberProto = $phoneUtil->parse($swissNumberStr, "CH");
    var_dump($swissNumberProto);
} catch (\libphonenumber\NumberParseException $e) {
    var_dump($e);
}

到此为止，swissNumberProto包含

class libphonenumber\PhoneNumber#9 (7) {
 private $countryCode =>
  int(41)
 private $nationalNumber =>
  double(446681800)
 private $extension =>
  NULL
 private $italianLeadingZero =>
  NULL
 private $rawInput =>
  NULL
 private $countryCodeSource =>
  NULL
 private $preferredDomesticCarrierCode =>
  NULL
}

现在让我们验证这个号码是否有效

$isValid = $phoneUtil->isValidNumber($swissNumberProto);
var_dump($isValid); // true

格式化方法支持几种格式，如下所示

// Produces "+41446681800"
echo $phoneUtil->format($swissNumberProto, \libphonenumber\PhoneNumberFormat::E164);

// Produces "044 668 18 00"
echo $phoneUtil->format($swissNumberProto, \libphonenumber\PhoneNumberFormat::NATIONAL);

// Produces "+41 44 668 18 00"
echo $phoneUtil->format($swissNumberProto, \libphonenumber\PhoneNumberFormat::INTERNATIONAL);

你也可以选择以其他国家拨打电话的方式格式化号码

// Produces "011 41 44 668 1800", the number when it is dialled in the United States.
echo $phoneUtil->formatOutOfCountryCallingNumber($swissNumberProto, "US");

// Produces "00 41 44 668 18 00", the number when it is dialled in Great Britain.
echo $phoneUtil->formatOutOfCountryCallingNumber($swissNumberProto, "GB");

地理编码器

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();

$swissNumberProto = $phoneUtil->parse("044 668 18 00", "CH");
$usNumberProto = $phoneUtil->parse("+1 650 253 0000", "US");
$gbNumberProto = $phoneUtil->parse("0161 496 0000", "GB");

$geocoder = \libphonenumber\geocoding\PhoneNumberOfflineGeocoder::getInstance();

// Outputs "Zurich"
echo $geocoder->getDescriptionForNumber($swissNumberProto, "en_US");

// Outputs "Zürich"
echo $geocoder->getDescriptionForNumber($swissNumberProto, "de_DE");

// Outputs "Zurigo"
echo $geocoder->getDescriptionForNumber($swissNumberProto, "it_IT");

// Outputs "Mountain View, CA"
echo $geocoder->getDescriptionForNumber($usNumberProto, "en_US");

// Outputs "Mountain View, CA"
echo $geocoder->getDescriptionForNumber($usNumberProto, "de_DE");

// Outputs "미국" (Korean for United States)
echo $geocoder->getDescriptionForNumber($usNumberProto, "ko-KR");

// Outputs "Manchester"
echo $geocoder->getDescriptionForNumber($gbNumberProto, "en_GB");

// Outputs "영국" (Korean for United Kingdom)
echo $geocoder->getDescriptionForNumber($gbNumberProto, "ko-KR");

短号信息

$shortNumberInfo = \libphonenumber\ShortNumberInfo::getInstance();

// true
var_dump($shortNumberInfo->isEmergencyNumber("999", "GB"));

// true
var_dump($shortNumberInfo->connectsToEmergencyNumber("999", "GB"));

// false
var_dump($shortNumberInfo->connectsToEmergencyNumber("911", "GB"));

// true
var_dump($shortNumberInfo->isEmergencyNumber("911", "US"));

// true
var_dump($shortNumberInfo->connectsToEmergencyNumber("911", "US"));

// false
var_dump($shortNumberInfo->isEmergencyNumber("911123", "US"));

// true
var_dump($shortNumberInfo->connectsToEmergencyNumber("911123", "US"));

电话号码与运营商的映射

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$swissNumberProto = $phoneUtil->parse("798765432", "CH");

$carrierMapper = \libphonenumber\PhoneNumberToCarrierMapper::getInstance();
// Outputs "Swisscom"
echo $carrierMapper->getNameForNumber($swissNumberProto, "en");

将电话号码映射到时区

$phoneUtil = \libphonenumber\PhoneNumberUtil::getInstance();
$swissNumberProto = $phoneUtil->parse("798765432", "CH");

$timeZoneMapper = \libphonenumber\PhoneNumberToTimeZonesMapper::getInstance();
// returns array("Europe/Zurich")
$timeZones = $timeZoneMapper->getTimeZonesForNumber($swissNumberProto);

常见问题解答

无效号码的问题？

这个库使用来自Google的libphonenumber的电话号码元数据。如果这个库按预期工作，它应该与Google项目的Java版本提供相同的结果。

如果你认为某个电话号码返回了错误的结果，首先通过他们的在线演示在libphonenumber中进行测试。如果返回的结果与这个项目相同，并且你认为有错误，请将问题作为一个问题提交给libphonenumber项目。

如果Google的在线演示与libphonenumber-for-php演示给出了不同的结果，那么请在这里提出问题。

生成数据

生成数据通常不需要，因为这个存储库通常会始终有最新的元数据。

如果你需要生成数据，Phing提供了命令。确保你已经安装了所有dev composer依赖项，然后运行

$ vendor/bin/phing compile

这个编译过程会克隆版本在METADATA-VERSION.txt中指定的libphonenumber项目。

运行测试

该项目使用PHPUnit Bridge以保持与支持的PHP版本的兼容性。

要本地运行测试，运行./phpunit脚本。

与框架集成

其他包存在，可以将libphonenumber-for-php集成到框架中。

这些包由第三方提供，其质量无法保证。