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

常见问题解答

无效号码的问题？

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

如果您认为某个电话号码返回了错误的结果，首先通过他们的在线演示使用libphonenumber进行测试。如果得到的结果与本项目相同，并且您认为这是错误的，请在libphonenumber项目中提出问题。

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

生成数据

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

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

$ vendor/bin/phing compile

此编译过程会根据METADATA-VERSION.txt中指定的版本克隆libphonenumber项目。

与框架集成

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

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