README

这是什么？

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

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

安装

目前支持 PHP 版本 5.3 至 PHP 7.3。

需要 PECL mbstring 扩展。

建议使用 composer 安装库。

$ composer require giggsey/libphonenumber-for-php

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

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

文档

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

常见问题解答

无效号码有问题吗？

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

如果您认为电话号码返回了不正确的结果，首先通过他们的 在线演示 使用 libphonenumber 进行测试。如果返回的结果与此项目相同，并且您认为它有误，请在 libphonenumber 项目中提出问题。

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

生成数据

生成数据通常不需要，因为这个仓库通常总是有最新的元数据。

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

$ vendor/bin/phing compile

此编译过程在 METADATA-VERSION.txt 中指定的版本下克隆了 libphonenumber 项目。

与框架集成

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

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