离线 IP 定位库 Ip2Region

本库基于 ip2region 的整合，方便 PHP 项目使用 Composer 安装和管理。

快速安装

通过 Composer 安装：

composer require zoujingli/ip2region

快速使用

简单查询示例：

$ip2region = new \Ip2Region();
$result = $ip2region->simple('8.8.8.8');
var_dump($result);

// 高级查询可以直接调用 XdbSearcher 类。

什么是 Ip2region

ip2region v2.0 是一个离线 IP 定位库和 IP 数据管理框架，提供高效查询（10 微秒级），支持主流编程语言的 xdb 数据生成与查询客户端。

特性

标准化的数据格式

每个 IP 数据段的 region 信息格式为：国家|区域|省份|城市|ISP。

中国数据精确到城市。
其他国家数据定位到国家。

数据去重和压缩

生成的 ip2region.xdb 默认大小为 11MiB，数据详细度增加时数据库大小随之增长。

极速查询响应

支持两种加速查询方式：

vIndex 索引缓存：使用 512KiB 内存缓存 vector index 数据，平均查询效率保持在 10-20 微秒。
xdb 文件缓存：将整个 xdb 文件加载至内存，无磁盘 IO，查询效率为微秒级。

可扩展 IP 数据管理框架

支持自定义 region 信息，如 GPS 数据、邮编等，满足特定业务需求。

查询使用方法

完全基于文件的查询

$dbFile = "ip2region.xdb";
try {
    $searcher = XdbSearcher::newWithFileOnly($dbFile);
} catch (Exception $e) {
    printf("创建搜索器失败: %s\n", $e->getMessage());
    return;
}

$ip = '1.2.3.4';
$sTime = XdbSearcher::now();
$region = $searcher->search($ip);
if ($region === null) {
    printf("查询失败: %s\n", $ip);
    return;
}

printf("{region: %s, took: %.5f ms}\n", $region, XdbSearcher::now() - $sTime);

缓存 VectorIndex 索引

$vIndex = XdbSearcher::loadVectorIndexFromFile($dbPath);
if ($vIndex === null) {
    printf("加载索引缓存失败: %s\n", $dbPath);
    return;
}

try {
    $searcher = XdbSearcher::newWithVectorIndex($dbFile, $vIndex);
} catch (Exception $e) {
    printf("创建索引缓存搜索器失败: %s\n", $e->getMessage());
    return;
}

$sTime = XdbSearcher::now();
$region = $searcher->search('1.2.3.4');
if ($region === null) {
    printf("查询失败: 1.2.3.4\n");
    return;
}

printf("{region: %s, took: %.5f ms}\n", $region, XdbSearcher::now() - $sTime);

缓存整个 xdb 数据

$cBuff = XdbSearcher::loadContentFromFile($dbPath);
if ($cBuff === null) {
    printf("加载 xdb 数据失败: %s\n", $dbPath);
    return;
}

try {
    $searcher = XdbSearcher::newWithBuffer($cBuff);
} catch (Exception $e) {
    printf("创建内存缓存搜索器失败: %s\n", $e->getMessage());
    return;
}

$sTime = XdbSearcher::now();
$region = $searcher->search('1.2.3.4');
if ($region === null) {
    printf("查询失败: 1.2.3.4\n");
    return;
}

printf("{region: %s, took: %.5f ms}\n", $region, XdbSearcher::now() - $sTime);