PHPackages zoujingli/ip2region - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. zoujingli/ip2region ActiveLibrary[Utility & Helpers](/categories/utility) zoujingli/ip2region =================== ip2region v3.0 for PHP - 企业级 IP 地理位置查询库，支持 IPv4 和 IPv6，多种缓存策略，零依赖，开箱即用 v3.0.15(1mo ago)1.4k475.0k—1.4%20620Apache-2.0PHPPHP >=7.1.0 Since Mar 22Pushed 1mo ago29 watchersCompare [ Source](https://github.com/zoujingli/ip2region)[ Packagist](https://packagist.org/packages/zoujingli/ip2region)[ Docs](https://github.com/zoujingli/Ip2Region)[ RSS](/packages/zoujingli-ip2region/feed)WikiDiscussions master Synced 2d ago READMEChangelog (10)DependenciesVersions (42)Used By (20) [![Latest Stable Version](https://camo.githubusercontent.com/26f597857d6aff2815ddb28ef8920d0d33aa282726fa9aab324bfb3bbe132b21/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f762f737461626c65)](https://packagist.org/packages/zoujingli/ip2region)[![Total Downloads](https://camo.githubusercontent.com/fea5425209aec0e2b48e106321adfd87d5e439382fe50beae8b657c0560dfa66/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f646f776e6c6f616473)](https://packagist.org/packages/zoujingli/ip2region)[![Monthly Downloads](https://camo.githubusercontent.com/38e079273c4a4ab6b7d0cf68ae7d36788ee3759693383cc2229ccfd85dcb8164/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f642f6d6f6e74686c79)](https://packagist.org/packages/zoujingli/ip2region)[![Daily Downloads](https://camo.githubusercontent.com/fcbcd1770c5d6b8906001b5b70a8d93cdb0e853f02f421639105d6b65f974ec7/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f642f6461696c79)](https://packagist.org/packages/zoujingli/ip2region)[![PHP Version Require](https://camo.githubusercontent.com/e979aea1bd08e6fdd94181ece97d19e49e74431caef04812a7d0a3bab28a9501/687474703a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f726571756972652f706870)](https://packagist.org/packages/ip2region)[![License](https://camo.githubusercontent.com/ee87b0a81848a3a55eab7bbf50e91082e0771e55c7f22606be589d7ed1f0e03a/68747470733a2f2f706f7365722e707567782e6f72672f7a6f756a696e676c692f697032726567696f6e2f6c6963656e7365)](https://packagist.org/packages/zoujingli/ip2region) ip2region v3.0 ============== [](#ip2region-v30) 🚀 **企业级 IP 地理位置查询库**：**支持 IPv4 和 IPv6**，智能加载，零依赖，**开箱即用**。 基于官方 [ip2region](https://github.com/lionsoul2014/ip2region) 深度优化，专为 PHP 项目定制，提供毫秒级 IP 地理位置查询服务。支持 IPv4 和 IPv6 双协议查询，具备智能加载机制和错误处理，**需要 PHP 7.1+**，全面使用类型声明提升代码质量和 IDE 支持，适用于企业级应用场景。 > ⚠️ **重要提示**： > > - **IPv4 查询**：✅ 开箱即用，无需下载 > - **IPv6 查询**：⚠️ **需要下载完整数据库**（约 36.09MB / 34.42MiB / 36086712 bytes），请使用 `./vendor/bin/ip2down download v6`（下载到 `vendor/bin/ip2data/` 后自动生效），或手动下载到 `db/` 或通过自定义路径提供 > 📢 **v3.0 更新**： > > - ✅ **代码优化**：工具代码减少 48.7%，更简洁高效 > - ✅ **开箱即用**：IPv4 查询无需下载，直接使用内置数据库文件 > - ✅ **按需下载**：IPv6 查询需要时再下载完整数据库 > - ✅ **多种缓存策略**：支持 file、vectorIndex、content 三种缓存模式 > - ✅ **简化部署**：直接使用未压缩的 xdb 文件，无需解压过程 > - ✅ **PHP 7.1+ 优化**：全面使用类型声明，提升代码质量和 IDE 支持 > - ✅ **字段映射修复**：修复 getIpInfo() 字段错位问题，region 字段已弃用 > 💡 **版本选择建议**： > > - **V3.0**：推荐使用，IPv4 开箱即用，IPv6 按需下载，自动缓存，代码更简洁 📦 核心特性 ------ [](#-核心特性) 特性描述**IPv4 支持**✅ 开箱即用，内置数据库文件**IPv6 支持**⚠️ 需要下载完整数据库（约 36.09MB / 34.42MiB / 36086712 bytes）**PHP 7.1+**✅ 需要 PHP 7.1+，全面使用类型声明缓存策略✅ 支持 file、vectorIndex、content 三种模式性能✅ 极快，微秒级响应零依赖✅ 纯 PHP 实现，无需额外扩展企业级✅ 完善的错误处理和性能监控🎯 项目简介 ------ [](#-项目简介) ip2region 是一个高性能的 IP 地址定位库，**支持 IPv4 和 IPv6 地址查询**。通过多种缓存策略，实现了大数据库文件的高效管理，为企业和开发者提供准确、快速的 IP 地理位置查询服务。 **V3.0 核心特性**： - 🚀 **开箱即用**：IPv4 查询无需下载，直接使用内置数据库文件 - ⚠️ **IPv6 按需下载**：IPv6 查询需要下载完整数据库（约 36.09MB / 34.42MiB / 36086712 bytes） - ⚡ **多种缓存策略**：支持 file、vectorIndex、content 三种缓存模式 - 📦 **简化部署**：直接使用未压缩的 xdb 文件，无需解压过程 - 🔧 **PHP 7.1+ 优化**：全面使用类型声明，提升代码质量和 IDE 支持 - ✅ **字段映射修复**：修复 getIpInfo() 字段错位，region 字段已弃用 **使用示例**： ``` echo ip2region('61.142.118.231'); // 输出：中国广东省中山市【电信】 echo ip2region('114.114.114.114'); // 输出：中国江苏省南京市 ``` ✨ 核心特性 ------ [](#-核心特性-1) - **🌍 双协议支持**：**支持 IPv4 和 IPv6 地址查询**，自动识别 IP 版本 - **⚡ 高性能**：基于官方 xdb 格式，查询速度极快，微秒级响应 - **📦 零依赖**：纯 PHP 实现，需要 PHP 7.1+，无需额外扩展 - **🚀 开箱即用**：IPv4 查询无需下载，直接使用内置文件 - **⚠️ IPv6 支持**：IPv6 查询需要下载完整数据库（约 36.09MB / 34.42MiB / 36086712 bytes） - **🔧 自定义数据库**：支持自定义 IPv4/IPv6 数据库路径配置 - **🔧 易集成**：支持 Composer 安装，提供函数式和面向对象两种 API - **💾 智能加载**：自动按优先级查找数据库文件，无需手动管理 - **⚡ 多种缓存策略**：支持 file、vectorIndex、content 三种缓存模式 - **📦 简化部署**：IPv4 使用未压缩数据库文件，无需解压过程 - **🛡️ 企业级**：完善的错误处理、异常管理和性能监控 - **🔄 懒加载**：IPv4/IPv6 查询器按需创建，优化内存使用 - **📦 PHAR 支持**：完全支持 PHAR 环境，自动检测并适配不同的文件系统，在 PHAR 中直接使用内置数据库 🏗️ 技术架构 ------- [](#️-技术架构) ### 自动加载机制 [](#自动加载机制) 项目采用优化的 Composer 自动加载策略： ``` { "autoload": { "psr-4": { "ip2region\\": "src/ip2region/" }, "classmap": [ "src/Ip2Region.php" ], "files": [ "src/common.php" ] } } ``` **设计特点**： - **PSR-4 加载**：`ip2region\xdb\*` 类使用 PSR-4 标准自动加载 - **全局类**：主类 `Ip2Region` 使用全局命名空间，便于直接使用 - **全局函数**：`src/common.php` 提供便捷的全局函数接口 - **组件化**：保持原有组件的命名空间和目录结构 ### 类结构设计 [](#类结构设计) ``` Ip2Region (全局类) ├── 使用 ip2region\xdb\IPv4 ├── 使用 ip2region\xdb\IPv6 └── 使用 ip2region\xdb\Searcher ip2region\xdb\* (组件类) ├── Util.php # 工具类 ├── IPv4.php # IPv4 处理 ├── IPv6.php # IPv6 处理 └── Searcher.php # 搜索引擎 ``` ### 工具集成 [](#工具集成) - **工具类设计**：`bin/ip2down` 使用内置类实现数据库管理功能 - **代码优化**：工具代码减少 48.7%，更简洁高效 - **减少依赖**：移除独立的 `DatabaseManager.php` 文件 - **简化维护**：所有工具功能集中在一个文件中 📁 项目结构 ------ [](#-项目结构) ``` ip2region/ ├── src/ # 核心源码 │ ├── Ip2Region.php # 主类（全局命名空间） │ └── ip2region/ │ └── xdb/ │ ├── Util.php # 工具类（ip2region\xdb\Util） │ ├── IPv4.php # IPv4 处理类（ip2region\xdb\IPv4） │ ├── IPv6.php # IPv6 处理类（ip2region\xdb\IPv6） │ └── Searcher.php # 搜索引擎类（ip2region\xdb\Searcher） ├── db/ # 数据库文件目录（内置 IPv4） │ └── ip2region_v4.xdb # IPv4 数据库文件（未压缩） ├── vendor/ │ └── bin/ │ └── ip2data/ # 下载的数据库文件缓存目录（`ip2down download` 会写入这里） │ ├── ip2region_v4.xdb # IPv4 数据库文件（可选） │ └── ip2region_v6.xdb # IPv6 数据库文件（可选） ├── bin/ # 命令行工具 │ └── ip2down # 数据库下载管理工具（内置类实现，支持实时进度显示） ├── tests/ # 测试文件 │ ├── demo.php # 演示程序 │ └── quick_performance_test.php # 性能测试脚本 ├── src/common.php # 全局函数入口 ├── composer.json # Composer 配置 └── README.md # 项目文档 ``` > **💡 重要提示**： > > - **IPv4 查询**：✅ 开箱即用，项目已包含数据库文件 > - **IPv6 查询**：⚠️ 需要下载完整数据库文件（约 36.09MB / 34.42MiB / 36086712 bytes），推荐使用 `ip2down download v6` > - **自定义数据库**：支持通过构造函数指定自定义数据库路径 > - **数据库文件**：IPv4 使用内置 xdb；IPv6 需下载后自动生效（可放到 `vendor/bin/ip2data/` 或 `db/`） 🆕 v3.0 新增功能 ----------- [](#-v30-新增功能) ### 数据库管理 [](#数据库管理) - **内置数据库**：IPv4 数据库直接包含在项目中，无需额外下载 - **简化部署**：使用未压缩的 xdb 文件，避免解压过程 - **智能加载**：自动按优先级查找数据库文件，简化使用 ### 增强的 API [](#增强的-api) - **双协议支持**：`ip2region()` 函数自动识别 IPv4/IPv6 - **面向对象**：`Ip2Region` 类提供完整的面向对象接口 - **批量查询**：`batchSearch()` 方法支持批量 IP 查询 - **性能监控**：`getStats()` 和 `getMemoryUsage()` 方法监控性能 ### 企业级特性 [](#企业级特性) - **错误处理**：完善的异常处理和错误提示 - **并发安全**：支持多进程/多线程安全使用 - **缓存策略**：支持文件、VectorIndex、完整数据三种缓存方式 - **PHP 7.1+ 要求**：需要 PHP 7.1 及以上版本 🚀 快速开始 ------ [](#-快速开始) ### 环境要求 [](#环境要求) - **PHP 版本**：>= 7.1.0 - **Composer**：用于安装和管理依赖 ### 1. 通过 Composer 安装 [](#1-通过-composer-安装) ``` # 安装 V3.0 版本（推荐，功能完整） composer require zoujingli/ip2region:^3.0 ``` ### 2. 下载数据库文件 [](#2-下载数据库文件) > 💡 **说明**：IPv4 数据库已内置到 `db/`，可开箱即用；IPv6 数据库需要额外下载（约 36.09MB / 34.42MiB / 36086712 bytes），下载后会被自动识别并使用。 **IPv4 查询**：✅ 开箱即用，无需下载 **IPv6 查询**：⚠️ 需要下载完整数据库文件 **方法一：使用下载工具（推荐）** ``` # 下载 IPv6 数据库（约 36.09MB / 34.42MiB / 36086712 bytes，支持实时进度显示） ./vendor/bin/ip2down download v6 # 下载所有数据库 ./vendor/bin/ip2down download all # 查看已下载的文件 ./vendor/bin/ip2down list # 测试数据库功能 ./vendor/bin/ip2down test # 清除下载的数据库文件 ./vendor/bin/ip2down clear ``` > **💡 开发环境提示**： 如果在开发环境中遇到 `./vendor/bin/ip2down: No such file or directory` 错误，可以使用以下命令： > > ``` > # 方法1：直接使用 PHP 运行 > php bin/ip2down download v6 > > # 方法2：创建符号链接 > ln -sf ../../bin/ip2down vendor/bin/ip2down > ``` **方法二：手动下载** ``` # 创建数据库目录 mkdir -p db # 下载 IPv6 数据库（约 36.09MB / 34.42MiB / 36086712 bytes） # 方法1：使用 GitHub 原始链接（推荐） # 首选：代理下载 wget -O db/ip2region_v6.xdb "https://gh-proxy.org/https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v6.xdb" # 备用：官方直链 # wget -O db/ip2region_v6.xdb "https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v6.xdb" # 方法2：使用 Gitee 镜像（国内访问更快，如果可用） # wget -O db/ip2region_v6.xdb "https://gitee.com/lionsoul/ip2region/raw/master/data/ip2region_v6.xdb" # 或者使用 curl（如果 wget 不可用） # 首选：代理下载 curl -L -o db/ip2region_v6.xdb "https://gh-proxy.org/https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v6.xdb" # 备用：官方直链 # curl -L -o db/ip2region_v6.xdb "https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region_v6.xdb" ``` > 💡 **下载提示**： > > - **IPv4**：已包含在项目中，无需下载（约 10.64MB / 10.15MiB / 10641955 bytes） > - **IPv6**：推荐使用 GitHub 原始链接，也可尝试 Gitee 镜像（如果可用） > - **文件大小**：IPv6 数据库约 36.09MB（34.42MiB / 36086712 bytes），建议使用原始链接或下载工具 **方法三：使用 Composer 脚本或下载工具** ``` # 下载 IPv6 数据库（约 36.09MB / 34.42MiB / 36086712 bytes，支持实时进度显示） ./vendor/bin/ip2down download v6 # 或者下载所有数据库 ./vendor/bin/ip2down download all # 尝试自动下载（可能因网络问题失败） composer download # 查看已下载的文件 ./vendor/bin/ip2down list # 测试数据库功能 ./vendor/bin/ip2down test ``` **进度显示特性**： - ✅ **实时进度**：显示已下载大小和下载速度 - ✅ **大小校验**：下载完成后按最小文件大小校验，避免保存错误页 - ✅ **流式下载**：避免大文件内存溢出 - ✅ **失败清理**：下载文件过小时自动清理，避免保留错误页或残缺文件 **进度显示示例**： ``` 开始下载 IPv6 数据库... 已下载: 9.02 MB 速度: 3.01 MB/s 已下载: 22.03 MB 速度: 3.67 MB/s 已下载: 30.05 MB 速度: 3.34 MB/s ... ✅ v6: 34.41 MB ``` > 📝 **注意**： > > - IPv4 数据库可以正常自动下载（约 10.64MB / 10.15MiB / 10641955 bytes） > - IPv6 数据库（约 36.09MB / 34.42MiB / 36086712 bytes），建议使用下载工具或手动下载 ### 数据库优先级 [](#数据库优先级) 系统按以下优先级查找数据库文件： 1. **自定义数据库**：通过构造函数指定的 `.xdb` 文件路径 2. **下载的数据库**：通过 `ip2down` 工具下载的完整数据库文件 3. **默认路径**：`db/` 目录下的内置 IPv4 文件；IPv6 可手动放入 `db/` > ⚠️ **重要**： > > - **IPv4**：使用未压缩 xdb 文件，开箱即用 > - **IPv6**：需要下载完整数据库文件（约 36.09MB / 34.42MiB / 36086712 bytes） ### 3. 自定义数据库配置 [](#3-自定义数据库配置) 项目已包含 IPv4 数据库文件，可直接使用。如需使用自定义数据库： ```