libphonenumber for php

PHP 的 libphonenumber

它是什麼？

用於解析、格式化、儲存和驗證國際電話號碼的 PHP 函式庫。該庫基於 Google 的 libphonenumber。

• 安裝
• 文件
• 線上示範
• 功能亮點
  • 版本控制
  • 快速範例
    • 地理編碼器
    • 短號碼訊息
    • 將電話號碼對應到運營商
    • 將電話號碼對應到時區
• 常問問題
  • 無效號碼有問題嗎？
• 產生數據
• 與框架集成

安裝

目前支援 PHP 7.4 至 PHP 8.4 版本。

需要 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，它提供的套件大小要小得多。

文件

• 電話號碼實用程式
• 短號訊息
• 電話號碼地理位置
• 電話號碼到運營商的映射
• 電話號碼到時區的映射
• 電話號碼匹配器
• 當您鍵入格式化程式時

線上示範

提供了線上演示，原始程式碼可以在 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 libphonenumberPhoneNumber#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 "[phone]"
echo $ phoneUtil -> format ( $ swissNumberProto , libphonenumber PhoneNumberFormat :: E164 );

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

// Produces "[phone]"
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 ( " [phone] " , " US " );
$ gbNumberProto = $ phoneUtil -> parse ( " 0161 496 0000 " , " GB " );

$ geocoder = libphonenumbergeocoding 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 整合到框架中的套件。

框架	套餐
交響樂團	電話號碼捆綁
拉維爾	Laravel 電話
伊伊2	電話輸入
小花	電話號碼
打字3	TYPO3 電話分機

這些包由第三方提供，其品質無法保證。