企业官网建设流程全解析

如何快速上手 ip-location-zh：一行 composer 命令，即刻获取 IP 省市与行政区划代码

【免费下载链接】ip-location-zh获取 IP 地址的真实地理位置项目地址: https://gitcode.com/gh_mirrors/ip/ip-location-zh

ip-location-zh是一个免费的 PHP 离线 IP 地理位置查询库：通过 IP 地址，一行代码即可查出该 IP 所属的国家、省份、城市以及中国行政区划代码（支持到市级），无需数据库、无需 API Key，composer一条命令即可安装使用。

📌 为什么选择 ip-location-zh？

很多项目都需要知道"这个用户从哪来"——日志留痕、风控防刷、区域化运营都会用到 IP 归属地。而大多数方案要么依赖第三方接口（慢、收费、受网络影响），要么要自己维护数据库。

ip-location-zh 的思路简单直接：内置一份离线 ipdb 数据库文件，纯 PHP 本地读取，即装即用。

它有几个很实用的特点：

1. ✅零配置——不依赖任何数据库，装好就能查
2. ✅功能专注——只做一个find方法，学习成本几乎为零
3. ✅composer 标准管理——升级包即可更新数据库
4. ✅自带行政区划代码——返回结果中包含省级/市级行政区划编码，做表单级联、地区校验特别方便

💡 注意：这是免费离线库，不提供经纬度、运营商、邮编等更细的信息；国外 IP 可以查到，但精度不如国内。需求简单的场景（省钱、求快）非常合适。

🚀 一键安装步骤

确保你已安装 PHP + Composer（安装 Composer 不在本文范围内），然后在项目根目录执行：

composer require "zhuzhichao/ip-location-zh"

就这一行。执行完成后，离线数据库文件20190703.ipdb会随包一起就位（位于src/目录下），库会自动加载它，不需要你做任何额外配置。

🧭 3 行代码完成 IP 省市查询

安装完成后，最小可用示例只有 3 行：

require 'vendor/autoload.php'; use Zhuzhichao\IpLocationZh\Ip; var_dump(Ip::find('171.12.10.156'));

返回一个数组，结构固定：

410100正是郑州市的行政区划代码——库内置了全国省市的编码映射（见 Ip.php 中的locations()方法），查省份级会返回省级编码，查城市级则精确到市级。

其他查询效果（来自 TestIp.php 的测试用例）：

⚡ Laravel 项目中的优雅用法

如果项目用的是 Laravel，体验会更顺：

1. 执行上面的composer require安装；
2. Laravel 5.5+支持服务包自动发现，无需任何注册配置；Laravel 5.0–5.4 则需在config/app.php的aliases中加入'Ip' => 'Zhuzhichao\IpLocationZh\Ip'（包的composer.json里已预置了该别名映射）；
3. 直接在任意控制器里使用：

Ip::find('171.12.10.156'); // 或者直接取当前访问者的真实 IP Ip::find(request()->getClientIp());

📁 项目文件结构一览

项目结构非常小巧，核心就两个文件：

❓ 常见疑问（FAQ）

Q1：IP 无效会怎样？传入空值返回N/A；传入非法格式（如999.1.1.1）会抛出InvalidArgumentException；查不到的 IP 同样返回N/A，建议调用前用filter_var($ip, FILTER_VALIDATE_IP)预校验。

Q2：数据是最新的吗？数据库为 2019-07-03 版本，由作者不定期更新。执行composer update即可获取新版数据文件。

Q3：性能如何？查询是纯本地文件读取（二分定位 + 位树遍历），且查询结果做了内存缓存——同一 IP 第二次查询直接命中缓存，高频调用毫无压力。

🎯 小结

如果你需要一个免费、离线、零配置的 PHP IP 归属地方案：

composer require "zhuzhichao/ip-location-zh"

然后一行Ip::find($ip)就能拿到国家 / 省 / 市 / 行政区划代码——从安装到跑通不超过 1 分钟，这就是 ip-location-zh 的"简单"之道。

【免费下载链接】ip-location-zh获取 IP 地址的真实地理位置项目地址: https://gitcode.com/gh_mirrors/ip/ip-location-zh