PHP 离线 IP 定位库 IP2region

🚀 引言

今天，我们来聊聊一个专为PHP设计的强大工具——ip2region库。它基于开源ip2region项目优化而来，提供企业级性能和灵活性，让开发者轻松实现本地IP查询。

“

🚀 企业级 IP 地理位置查询库：基于官方 ip2region 深度优化，支持 IPv4/IPv6，分片文件管理，智能压缩，零依赖

“

⚠️ 重要提示：由于 V3.0 版本新增了 IPv6 数据库支持，尽管已进行智能压缩优化，但整体体积仍超过 100MB。如果您仅需 IPv4 查询功能，建议使用 V2 版本以获得更小的体积和更快的加载速度。

💡 为什么选择离线IP定位？

想象一下，你的网站需要实时显示访客所在城市，但又不想每次都调用外部服务。这不仅能节省成本，还能提升响应速度。ip2region库正是为此而生。它使用本地数据库文件进行查询，无需互联网连接，支持IPv4和IPv6双协议。这意味着无论你是处理传统网络还是新兴IPv6环境，都能无缝集成。更重要的是，它零依赖于外部扩展，只需纯PHP环境即可运行，兼容从PHP 5.4到最新版本。

📦 版本选择

“

⚠️ 重要提示：默认的 composer require zoujingli/ip2region 命令会安装 V3.0 版本。如需 V2.0 版本，请使用 composer require zoujingli/ip2region:^2.0。

🎯 项目简介

ip2region 是一个高性能的 IP 地址定位库，支持 IPv4 和 IPv6 地址查询。通过智能分片和压缩技术，实现了大数据库文件的高效管理，为企业和开发者提供准确、快速的 IP 地理位置查询服务。

“

📖 V2.0 版本文档：如果您仅需 IPv4 查询功能，建议使用 V2.0 版本，体积更小（10MB+），加载更快。

✨ 核心特性

• 🌍 双协议支持：完整支持 IPv4 和 IPv6 地址查询，自动识别 IP 版本
• ⚡ 高性能：基于官方 xdb 格式，查询速度极快，微秒级响应
• 📦 零依赖：纯 PHP 实现，兼容 PHP 5.4+，无需额外扩展
• 🔧 自定义数据库：支持自定义 IPv4/IPv6 数据库路径配置
• 🔧 易集成：支持 Composer 安装，提供函数式和面向对象两种 API
• 💾 智能缓存：支持文件缓存、VectorIndex 缓存、完整数据缓存
• 📊 分片管理：大文件自动分片（<100MB），支持按需加载和合并
• 🗜️ 智能压缩：支持 gzip、zip、zstd 多种压缩格式，压缩率高达 81%
• 🛡️ 企业级：完善的错误处理、异常管理和性能监控
• 🔄 懒加载：IPv4/IPv6 查询器按需创建，优化内存使用
• 💡 零配置：开箱即用，自动检测数据库版本和格式

📁 项目结构

ip2region/├──src/                    # 核心源码
│   ├──Ip2Region.php      # 主类，支持 IPv4/IPv6 双协议
│   ├──XdbSearcher.php    # 官方 xdb 查询器封装
│   └──ChunkedDbHelper.php# 分片文件管理助手
├──db/                    # 分片数据库文件（自动生成）
│   ├──ip2region_v4.xdb.part1    # IPv4 数据库分片
│   └──ip2region_v6.xdb.part*    # IPv6 数据库分片（多个文件）
├──tools/                 # 工具脚本
│   ├──split_db.php       # 数据库分片工具（重要！）
│   ├──ip2region_v4.xdb   # IPv4 完整数据库（需要下载）
│   └──ip2region_v6.xdb   # IPv6 完整数据库（需要下载）
├──tests/                 # 测试文件
│   └──demo.php           # 演示程序
├──function.php           # 全局函数入口
├──composer.json          # Composer 配置
└──README.md              # 项目文档

“

💡 重要提示：

• db/ 目录中的分片文件是通过 tools/split_db.php 工具从 tools/ 目录的完整数据库文件生成的
• tools/ 目录中的 ip2region_v4.xdb 和 ip2region_v6.xdb 是原始数据库文件，仅用于分片工具
• 文件名必须严格按照 ip2region_v4.xdb 和 ip2region_v6.xdb 命名，不能有任何变化
• 项目已包含分片文件，可直接使用，无需手动生成

🆕 v3.0 新增功能

智能分片管理

• 自动分片：大文件自动分割为 <100MB 的小文件
• 压缩支持：支持 gzip/zip 压缩，显著减小文件大小（压缩率可达 60-80%）
• 按需合并：首次使用时自动解压并合并分片文件
• 智能缓存：合并后的文件缓存到临时目录，避免重复解压合并
• 内存优化：支持懒加载，IPv4/IPv6 查询器按需创建

增强的 API

• 双协议支持：ip2region() 函数自动识别 IPv4/IPv6
• 面向对象：Ip2Region 类提供完整的面向对象接口
• 批量查询：batchSearch() 方法支持批量 IP 查询
• 性能监控：getStats() 和 getMemoryUsage() 方法监控性能

企业级特性

• 错误处理：完善的异常处理和错误提示
• 并发安全：支持多进程/多线程安全使用
• 缓存策略：支持文件、VectorIndex、完整数据三种缓存方式
• PHP 5.4+ 兼容：完全兼容 PHP 5.4 及以上版本

🚀 快速开始

1. 通过 Composer 安装

# 安装 V3.0 版本（推荐，功能完整）
composer require zoujingli/ip2region:^3.0
# 或安装 V2.0 版本（轻量级，仅 IPv4）
composer require zoujingli/ip2region:^2.0

2. 数据库文件准备

项目已包含分片数据库文件，可直接使用。如需使用自定义数据库：

# 下载完整数据库文件到 tools/ 目录
# 然后生成分片文件
php tools/split_db.php v4    # IPv4 分片
php tools/split_db.php v6    # IPv6 分片

3. 一行代码开始使用

<?php
require'vendor/autoload.php';
// 最简单的使用方式
echo ip2region('61.142.118.231') . "\n"; // 中国广东省中山市【电信】
echo ip2region('2001:4860:4860::8888') . "\n"; // 美国加利福尼亚州圣克拉拉【专线用户】
// 使用不同查询方法
echo ip2region('61.142.118.231', 'search') . "\n"; // 中国|广东省|中山市|电信
echo ip2region('61.142.118.231', 'memory') . "\n"; // 返回数组格式
// 或者使用类方式
$ip2region = new \Ip2Region();echo $ip2region->simple('61.142.118.231') . "\n"; // 中国广东省中山市【电信】
// 使用自定义数据库（可选）
$ip2region = new \Ip2Region('file', '/path/to/ip2region_v4.xdb', '/path/to/ip2region_v6.xdb');
echo $ip2region->simple('8.8.8.8') . "\n"; // 美国【Level3】
?>

4. 验证安装

# 测试 IPv4 查询
composer test:ipv4
# 测试 IPv6 查询
composer test:ipv6
# 测试不同查询方法
composer test:search    
# 详细查询
composer test:memory    
# 内存查询# 查询指定
IPcomposer query 61.142.118.231
composer query:search 61.142.118.231
composer query:memory 61.142.118.231
# 运行演示程序
composer demo

在项目中快速调用

函数式调用

<?php
require'vendor/autoload.php';
// 简单查询
echo ip2region('61.142.118.231') . "\n";        // 中国广东省中山市【电信】
echo ip2region('2001:4860:4860::8888') . "\n"; // 美国加利福尼亚州圣克拉拉【专线用户】
// 使用不同查询方法echo ip2region('61.142.118.231', 'search') . "\n"; 
// 中国|广东省|中山市|电信echo ip2region('61.142.118.231', 'memory') . "\n"; 
// 返回数组格式// 批量查询$ips = ['61.142.118.231', '114.114.114.114', '2001:4860:4860::8888'];
foreach ($ips as $ip) {
    echo"$ip => " . ip2region($ip) . "\n";
}
?>

面向对象调用

<?php
require'vendor/autoload.php';
try { 
  // 默认模式（使用分片数据库）   
$ip2region = new \Ip2Region();        // 如需使用自定义数据库，请参考下面的"自定义数据库配置"部分    
// $ip2region = new \Ip2Region('file', '/path/to/your/ip2region_v4.xdb', '/path/to/your/ip2region_v6.xdb');    
// 基础查询    
echo $ip2region->simple('61.142.118.231') . "\n";    
echo $ip2region->search('2001:4860:4860::8888') . "\n";    
// 获取详细信息   
$info = $ip2region->getIpInfo('61.142.118.231');    print_r($info);    
// 输出: Array(    
//   [country] => 中国    
//   [region] => 广东省    
//   [province] => 中山市    
//   [city] => 电信    
//   [isp] =>    
//   [ip] => 61.142.118.231    
//   [version] => v4    
// )    
// 批量查询   
$results = $ip2region->batchSearch(['61.142.118.231', '114.114.114.114']);
    print_r($results);    
// 性能监控   
$stats = $ip2region->getStats();    
echo"内存使用: " . $stats['memory_usage'] . " bytes\n";   
echo"IPv4 已加载: " . ($stats['v4_loaded'] ? '是' : '否') . "\n";    
echo"IPv6 已加载: " . ($stats['v6_loaded'] ? '是' : '否') . "\n";
} catch (Exception $e) {    
echo"错误: " . $e->getMessage() . "\n";}
?>

自定义数据库配置

<?php
require'vendor/autoload.php';
try {    
// 使用自定义数据库路径（建议使用绝对路径）   
$ip2region = new \Ip2Region('file', '/path/to/your/ip2region_v4.xdb', '/path/to/your/ip2region_v6.xdb');    
// 查询IP    
echo $ip2region->simple('8.8.8.8') . "\n";    
// 检查是否使用自定义数据库   
$customStatus = $ip2region->isUsingCustomDb();    
echo"IPv4 使用自定义数据库: " . ($customStatus['v4'] ? '是' : '否') . "\n";    
echo"IPv6 使用自定义数据库: " . ($customStatus['v6'] ? '是' : '否') . "\n";    
// 动态设置数据库路径    
$ip2region->setCustomDbPaths('/path/to/v4.xdb', '/path/to/v6.xdb');    
// 获取数据库配置信息    
$dbInfo = $ip2region->getDatabaseInfo();   
echo"IPv4 路径: " . ($dbInfo['custom_v4_path'] ?: '默认分片') . "\n";    
echo"IPv6 路径: " . ($dbInfo['custom_v6_path'] ?: '默认分片') . "\n";
} catch (Exception $e) {   
 echo"错误: " . $e->getMessage() . "\n";
}
?>