README

特性

• 纯PHP实现，无需扩展
• 高性能二分查找算法
• 与Go版本完全兼容的数据格式
• 支持所有中国电信运营商
• 简单易用的API

安装

1. 下载本项目到你的PHP项目中
2. 确保 phone.dat 数据文件与 Location.php 在同一目录下
3. 或者通过环境变量 PHONE_DATA_DIR 指定数据文件目录

快速开始

基本使用

require_once 'Location.php';

// 创建Location实例
$phoneData = new Location();

// 查询手机号归属地
try {
    $result = $phoneData->find('18957509123');
    print_r($result);
} catch (Exception $e) {
    echo "错误: " . $e->getMessage();
}

// 输出格式化的字符串
try {
    echo $phoneData->findString('18957509123');
} catch (Exception $e) {
    echo "错误: " . $e->getMessage();
}

输出示例

Array
(
    [phoneNum] => 18957509123
    [province] => 浙江
    [city] => 绍兴
    [zipCode] => 312000
    [areaZone] => 0575
    [cardType] => 中国电信
)

或者：

PhoneNum: 18957509123
AreaZone: 0575
CardType: 中国电信
City: 绍兴
ZipCode: 312000
Province: 浙江

API文档

构造函数

new Location(string $dataDir = null)

创建Location实例。

参数：

• $dataDir (string|null): 数据文件目录，如果为null则使用环境变量PHONE_DATA_DIR或默认目录

实例方法

find(string $phoneNum): array

查找手机号归属地信息。

参数：

• $phoneNum (string): 手机号码（7-11位）

返回值：

• 包含以下键的数组：
  • phoneNum: 手机号码
  • province: 省份
  • city: 城市
  • zipCode: 邮编
  • areaZone: 长途区号
  • cardType: 运营商类型

异常：

• InvalidArgumentException: 手机号格式错误
• RuntimeException: 找不到手机号信息或数据文件错误

findString(string $phoneNum): string

查找手机号归属地信息并返回格式化的字符串。

参数：

• $phoneNum (string): 手机号码（7-11位）

返回值：

• 格式化的字符串（与Go版本输出格式相同）

findBatch(array $phoneNumbers): array

批量查询手机号归属地信息。

参数：

• $phoneNumbers (array): 手机号码数组

返回值：

• 包含两个键的数组：
  • success: 成功查询的结果数组
  • failed: 失败查询的错误信息数组

debug(): void

输出调试信息，包括版本号、总记录数和第一个记录偏移量。

version(): string

获取数据文件版本号。

totalRecord(): int

获取总记录数。

firstRecordOffset(): int

获取第一个记录的偏移量。

getInfo(): array

获取数据文件信息。

返回值：

• 包含以下键的数组：
  • version: 数据文件版本
  • totalRecords: 总记录数
  • firstOffset: 第一个记录偏移量
  • fileSize: 文件大小
  • dataDir: 数据文件目录

数据文件格式

文件结构

| 4 bytes |                     <- 版本号（如：1701即17年1月份）
------------
| 4 bytes |                     <- 第一个索引的偏移
-----------------------
|  offset - 8            |      <- 记录区
-----------------------
|  index                 |      <- 索引区
-----------------------

记录区格式

每条记录的格式为："<省份>|<城市>|<邮编>|<长途区号>\0"

索引区格式

每条索引的格式为："<手机号前七位><记录区的偏移><卡类型>"，每个索引的长度为9个字节。

卡类型映射

性能

PHP版本使用与Go版本相同的二分查找算法，性能优秀。在普通服务器上，单次查询通常在0.1-0.5毫秒内完成。

注意事项

1. 确保 phone.dat 文件具有读取权限
2. 手机号长度必须在7-11位之间
3. 数据文件需要定期更新以获取最新的号段信息
4. 在生产环境使用前请自行测试验证