README

这是什么？

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

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

安装

当前支持PHP版本5.3至PHP 7.2。HHVM也受支持。

需要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);

常见问题解答

无效号码的问题？

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

如果您认为电话号码返回了错误的结果，请首先通过他们的 在线演示 使用 libphonenumber 进行测试。如果返回的结果与本项目相同，并且您认为存在错误，请将问题作为Issue提交给libphonenumber项目。

如果Google的 在线演示 给出的结果与 libphonenumber-for-php演示 不同，请在此处提出Issue。

生成数据

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

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

$ vendor/bin/phing compile

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

与框架集成

存在其他一些将libphonenumber-for-php集成到框架中的包。

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