README

面向 ThinkPHP 的开源工程索引：组件、框架、服务与发布工具，按能力组织，持续整理。仓库地址：https://github.com/indiboy-create/ThinkPHP-PanGu/ 在线站点：https://indiboy-create.github.io/ThinkPHP-PanGu/

think-ip2region

youvision/think-ip2region 是 zoujingli/ip2region 的 ThinkPHP 8 集成扩展。它在保持底层 XDB 查询能力的同时，提供容器绑定、门面、助手函数、结构化解析、查询结果缓存、客户端 IP 自动识别和特殊地址处理。

环境要求

PHP >= 8.0
ThinkPHP >= 8.0
zoujingli/ip2region >= 3.0（由 Composer 自动安装，内置 IPv4 数据库）

安装

composer require youvision/think-ip2region

ThinkPHP 8 会通过 extra.think.services 自动注册服务，无需手动修改配置。若项目未执行服务发现，请运行：

php think service:discover

或在 app/service.php 中手动注册：

return [
    \youvision\think\ip2region\Service::class,
];

如需调整配置，发布配置文件：

php think vendor:publish

执行后会生成 config/ip2region.php（已存在时不会覆盖，需覆盖请加 --force）。

快速开始

门面

use youvision\think\ip2region\facade\Ip2Region;

// 格式化文案：中国广东省中山市【电信】
echo Ip2Region::simple('61.142.118.231');

// 数据库原始字符串：中国|广东省|中山市|电信|CN
echo Ip2Region::search('61.142.118.231');

// 结构化数组
$region = Ip2Region::region('61.142.118.231');
// [
//     'ip'       => '61.142.118.231',
//     'valid'    => true,
//     'special'  => '',
//     'country'  => '中国',
//     'province' => '广东省',
//     'city'     => '中山市',
//     'isp'      => '电信',
//     'code'     => 'CN',
//     'region'   => '中国|广东省|中山市|电信|CN',
//     'version'  => 'v4',
//     'error'    => '',
// ]

助手函数

// 不传 IP 时自动读取当前请求的客户端 IP
echo ip_region();

// 指定返回类型：simple、search、region、info
echo ip_region('8.8.8.8');
echo ip_region('8.8.8.8', 'search');
$region = ip_region('8.8.8.8', 'region');

依赖注入

use youvision\think\ip2region\Ip2Region;

class Visit
{
    public function __construct(protected Ip2Region $ip2region)
    {
    }

    public function record(string $ip): void
    {
        $region = $this->ip2region->region($ip);
    }
}

批量查询

$result = \youvision\think\ip2region\facade\Ip2Region::batch([
    '61.142.118.231',
    '8.8.8.8',
    '114.114.114.114',
], 'region');

// 返回以 IP 为键的数组

高级查询

需要调用底层 zoujingli/ip2region 的完整 API 时：

$searcher = \youvision\think\ip2region\facade\Ip2Region::getSearcher();

$info = $searcher->getIpInfo('61.142.118.231');
$stats = $searcher->getStats();

配置说明

配置文件位于 config/ip2region.php，所有配置项均在代码中实际读取生效。

配置项	默认值	说明
`enable`	`true`	是否启用查询。关闭后不加载数据库，查询统一返回 `unknown` 文案
`db_path_v4`	`''`	IPv4 XDB 绝对路径。留空使用依赖包默认查找顺序
`db_path_v6`	`''`	IPv6 XDB 绝对路径。留空使用依赖包默认查找顺序
`cache_policy`	`'file'`	底层 XDB 查询器策略：`file`、`vectorIndex`、`content`
`cache.enable`	`false`	是否启用查询结果缓存（ThinkPHP Cache）
`cache.store`	`null`	缓存驱动名称，留空使用默认驱动
`cache.ttl`	`86400`	查询结果缓存有效期（秒），`0` 表示永久
`cache.prefix`	`'ip2region:'`	查询结果缓存键前缀
`format`	`'{country}{province}{city}【{isp}】'`	`simple()` 文案模板
`separator`	`'	'`
`unknown`	`'未知'`	无法识别时的返回文案
`silent`	`true`	是否静默处理查询异常。`false` 时异常向上抛出
`request_ip`	`true`	未传 IP 时是否自动读取请求客户端 IP
`special.*`	见配置文件	特殊用途地址的显示文案

format 支持占位符：{country}、{province}、{city}、{isp}、{code}、{region}。

缓存策略

cache_policy 控制底层查询器如何加载 XDB 文件：

file：只缓存文件句柄，内存占用最低，适合普通 Web 请求。
vectorIndex：将向量索引载入内存，查询更快，适合高频查询。
content：将整个 XDB 文件载入内存，速度最快，适合 Swoole/Workerman 常驻进程。

cache.enable 控制的是查询结果缓存，两者互不影响。

IPv6 支持

依赖包默认仅内置 IPv4 数据库。查询 IPv6 前需准备 ip2region_v6.xdb：

php vendor/zoujingli/ip2region/bin/ip2down download v6

或在 config/ip2region.php 中指定绝对路径：

'db_path_v6' => app()->getRootPath() . 'data/ip2region_v6.xdb',

未准备 IPv6 数据库时，查询 IPv6 会在 silent=true 下返回 未知，不会中断业务流程。生产环境建议配置 silent=false 以便及时发现数据库缺失。

特殊地址

以下地址不会查询数据库，直接返回 special 中配置的文案：

类型	示例
回环地址	`127.0.0.1`、`::1`
私网地址	`10.0.0.1`、`172.16.0.1`、`192.168.1.1`、`fc00::1`
链路本地地址	`169.254.1.1`、`fe80::1`
未指定地址	`0.0.0.0`、`::`
组播地址	`224.0.0.1`、`ff02::1`
保留地址	`240.0.0.1`

测试

composer install
vendor/bin/phpunit

许可证

Apache-2.0

youvision / think-ip2region

Package info

Security

Statistics