Download the PHP package zoujingli/ip2region without Composer

On this page you can find all versions of the php package zoujingli/ip2region. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.

FAQ

After the download, you have to make one include require_once('vendor/autoload.php');. After that you have to import the classes with use statements.

Example:
If you use only one package a project is not needed. But if you use more then one package, without a project it is not possible to import the classes with use statements.

In general, it is recommended to use always a project to download your libraries. In an application normally there is more than one library needed.
Some PHP packages are not free to download and because of that hosted in private repositories. In this case some credentials are needed to access such packages. Please use the auth.json textarea to insert credentials, if a package is coming from a private repository. You can look here for more information.

  • Some hosting areas are not accessible by a terminal or SSH. Then it is not possible to use Composer.
  • To use Composer is sometimes complicated. Especially for beginners.
  • Composer needs much resources. Sometimes they are not available on a simple webspace.
  • If you are using private repositories you don't need to share your credentials. You can set up everything on our site and then you provide a simple download link to your team member.
  • Simplify your Composer build process. Use our own command line tool to download the vendor folder as binary. This makes your build process faster and you don't need to expose your credentials for private repositories.
Please rate this library. Is it a good library?

Example code of zoujingli/ip2region

Informations about the package ip2region

Latest Stable Version Total Downloads Monthly Downloads Daily Downloads PHP Version Require License

ip2region v3.0

🚀 企业级 IP 地理位置查询库：支持 IPv4 和 IPv6，智能加载，零依赖，开箱即用。

基于官方 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 核心特性：

使用示例：

✨ 核心特性

🏗️ 技术架构

自动加载机制

项目采用优化的 Composer 自动加载策略：

设计特点：

类结构设计

工具集成

📁 项目结构

💡 重要提示：

  • IPv4 查询：✅ 开箱即用，项目已包含数据库文件
  • IPv6 查询：⚠️ 需要下载完整数据库文件（约 36.09MB / 34.42MiB / 36086712 bytes），推荐使用 ip2down download v6
  • 自定义数据库：支持通过构造函数指定自定义数据库路径
  • 数据库文件：IPv4 使用内置 xdb；IPv6 需下载后自动生效（可放到 vendor/bin/ip2data/ 或 db/）

🆕 v3.0 新增功能

数据库管理

增强的 API

企业级特性

🚀 快速开始

环境要求

1. 通过 Composer 安装

2. 下载数据库文件

💡 说明：IPv4 数据库已内置到 db/，可开箱即用；IPv6 数据库需要额外下载（约 36.09MB / 34.42MiB / 36086712 bytes），下载后会被自动识别并使用。

IPv4 查询：✅ 开箱即用，无需下载 IPv6 查询：⚠️ 需要下载完整数据库文件

方法一：使用下载工具（推荐）

💡 开发环境提示： 如果在开发环境中遇到 ./vendor/bin/ip2down: No such file or directory 错误，可以使用以下命令：

方法二：手动下载

💡 下载提示：

  • IPv4：已包含在项目中，无需下载（约 10.64MB / 10.15MiB / 10641955 bytes）
  • IPv6：推荐使用 GitHub 原始链接，也可尝试 Gitee 镜像（如果可用）
  • 文件大小：IPv6 数据库约 36.09MB（34.42MiB / 36086712 bytes），建议使用原始链接或下载工具

方法三：使用 Composer 脚本或下载工具

进度显示特性：

进度显示示例：

📝 注意：

  • 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. 自定义数据库配置

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

获取数据库文件：

3. 一行代码开始使用

4. 验证安装

在项目中快速调用

函数式调用

面向对象调用

自定义数据库配置

数据库文件准备

数据库加载优先级

ip2region 库按照以下优先级自动查找数据库文件：

  1. 自动路径：通过构造函数指定的自定义数据库路径
  2. vendor 目录：vendor/bin/ip2data/ 目录下的下载文件
  3. 默认路径：db/ 目录下的内置文件（本仓库内置 IPv4；IPv6 需下载到 vendor/bin/ip2data/ 或通过自定义路径提供）

使用预置数据库

本仓库已包含 IPv4 官方数据库文件，位于 db/ 目录：

PHAR 环境使用

在 PHAR 环境中，ip2region 库会自动检测环境并调整数据库加载策略：

PHAR 环境特点：

使用自定义数据库

如果需要使用自定义的数据库文件，请按以下步骤操作：

1. 获取完整数据库文件

重要：IPv4 数据库文件已包含在 db/ 目录，可直接使用：

文件说明：

获取数据库文件：

2. 放置数据库文件

将下载的数据库文件放置到 db/ 目录：

3. 验证数据库文件

Composer 脚本

项目提供了便捷的 Composer 脚本命令：

核心功能

数据库管理

工具命令

API 参考

全局函数

ip2region($ip, $method = 'simple')

查询方法对比

方法名 描述 返回值类型 性能特点 适用场景 示例输出
simple 简单查询（默认） string 最快 一般查询，用户友好显示 中国广东省中山市【电信】
search 详细查询 string 快 需要原始数据格式 中国\|广东省\|中山市\|电信\|CN
memory 内存查询 array 快 需要结构化数据 {"city_id":0,"region":"中国\|广东省\|中山市\|电信\|CN"}
binary 二进制搜索 array 中等 有序数据快速查找 {"city_id":0,"region":"中国\|广东省\|中山市\|电信\|CN"}
btree B 树索引 array 中等 大规模数据平衡查询 {"city_id":0,"region":"中国\|广东省\|中山市\|电信\|CN"}

使用建议

Ip2Region 类

构造函数

核心查询方法

simple($ip)
search($ip)
memorySearch($ip)
batchSearch($ips)
getIpInfo($ip)

兼容性方法

binarySearch($ip)
btreeSearch($ip)
searchByBytes($ipBytes)

工具方法

getStats()
getMemoryUsage()
getIOCount()
getProtocolVersion($ip)
isIPv4Supported()
isIPv6Supported()
getDatabaseInfo()
setCustomDbPaths($v4Path, $v6Path)
isUsingCustomDb()
getCustomDbInfo()

性能监控示例

缓存管理示例

FPM 环境优化

缓存策略优化

ip2region 支持三种缓存策略，可根据不同使用场景选择最优策略：

缓存策略说明

  1. file 模式（默认）：

    • 适合大文件，内存占用少
    • 首次查询较慢，后续查询快
    • 适合单次查询或低频查询场景

  2. vectorIndex 模式：

    • 减少 IO 操作，提升查询速度
    • 内存占用适中
    • 适合频繁查询场景
  3. content 模式：
    • 零 IO 操作，查询最快
    • 占用大量内存
    • 适合高并发场景

使用示例

性能对比

缓存策略 内存使用 IO 次数 查询速度 适用场景
file 低 多 中等 单次查询
vectorIndex 中等 少 快 频繁查询
content 高 无 最快 高并发

性能测试

快速性能测试

运行 composer performance 进行快速性能测试：

测试结果示例：

性能测试内容

快速性能测试包含以下项目：

性能特点

测试环境

性能指标

  1. 首次加载：直接使用数据库文件，IPv4 约 0.71ms，IPv6 约 0.71ms (new Ip2Region() + simple())
  2. 缓存命中：IPv4 约 0.16ms，IPv6 约 0.16ms (new Ip2Region() + simple())
  3. 性能表现：查询速度快，内存占用低，缓存效果显著
  4. 查询方法：
    • simple()：约 0.02ms (格式化输出)
    • search()：约 0.01ms (原始数据)
    • memorySearch()：约 0.01ms (数组格式)
  5. 批量查询：
    • 10个IP：约 1.19ms (8403 QPS) (ip2region->batchSearch())
    • 10000个IP：约 89.94ms (111185 QPS) (ip2region->batchSearch())
    • 10000次循环：约 53.86ms (185667 QPS) (10000次 ip2region->simple())
  6. 内存使用：当前 4MB，峰值 4MB
  7. 性能监控：约 0.01ms (getStats() 性能监控)
  8. 性能评分：100/100 (优秀 ⭐⭐⭐⭐⭐)

最新性能测试结果 (2025-10-18)

测试环境：

详细性能数据：

性能等级说明

故障排除

常见问题

1. 数据库文件不存在

错误信息：数据库文件不存在: /path/to/ip2region_v4.xdb 解决方案：

文件摆放检查：

2. 内存不足

错误信息：Fatal error: Allowed memory size exhausted 解决方案：

3. 数据库文件损坏

错误信息：数据库文件不存在 或 无法读取数据库文件 解决方案：

4. 并发使用问题

错误信息：Too many open files 解决方案：

性能优化建议

  1. 选择合适的缓存策略：

    • file 模式：适合大文件，内存占用少，首次查询较慢
    • vectorIndex 模式：减少 IO 操作，提升查询速度，内存占用适中
    • content 模式：零 IO 操作，查询最快，但占用大量内存

  2. 根据使用场景选择：

    • 单次查询：使用 file 策略
    • 频繁查询：使用 vectorIndex 策略
    • 高并发：使用 content 策略

  3. 批量查询优化：

    • 使用 batchSearch() 方法进行批量查询
    • 避免在循环中重复创建实例

  4. 内存管理：

    • 定期清理过期缓存
    • 监控内存使用情况
    • 使用懒加载特性

  5. 文件管理：

    • 定期检查文件完整性
    • 使用 getStats() 监控性能状态
    • 根据使用场景选择合适的缓存策略
  6. 性能优化建议：
    • 选择合适的缓存策略：根据使用场景选择 file、vectorIndex 或 content 模式
    • 定期检查文件完整性：确保数据库文件完整无损
    • 监控内存使用：根据内存情况选择合适的缓存策略

许可证

本项目基于 Apache-2.0 许可证开源。

🔧 通用查询函数

IP2Region 提供了通用的 ip2region() 函数，支持多种查询方法：

函数签名

支持的查询方法

方法 描述 返回值 示例
simple 简单查询（默认） 格式化的地理位置字符串，特殊地址返回地址类型 "中国广东省中山市【电信】" / "回环地址"
search 详细查询 管道分隔的详细信息 "中国\|广东省\|中山市\|电信\|CN"
binary 二进制查询 原始二进制数据 二进制字符串
btree B 树查询 B 树索引查询结果 查询结果字符串
memory 内存查询 内存中的查询结果 查询结果字符串

使用示例

特性说明

📚 相关链接

贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目。

联系方式

如有问题或建议，请通过以下方式联系：

All versions of ip2region with dependencies

PHP Build Version
Package Version
Requires php Version >=7.1.0
Composer command for our command line client (download client) This client runs in each environment. You don't need a specific PHP version etc. The first 20 API calls are free. Standard composer command

The package zoujingli/ip2region contains the following files

Loading the files please wait ...