尧图网页设计 
后端【免费下载链接】YOURLS The standard, self hosted, powerful and customizable, URL shortener in PHP项目地址https://gitcode.com/gh_mirrors/yo/YOURLS点击查看免费下载导读MaxMind DB 是一种以 IP 网段IPv4 或 IPv6为索引的二进制数据库格式MaxMind DB Reader PHP API 则是读取该格式的标准 PHP 客户端。本文以 YOURLS 仓库内 maxmind-db/reader 的 README 为主体结合 Reader.php、Decoder.php 等源码系统讲解安装方式、核心 API 用法、C 扩展加速方案、128 位整数支持与底层查询原理并说明 YOURLS 是如何利用该生态实现 IP 到国家/地区定位的。读完本文你将能够独立完成 MaxMind DB 读取环境的搭建与 IP 地理定位查询并理解其二进制检索树的实现细节。MaxMind DB 格式与 Reader 库定位MaxMind DB 是一个二进制文件格式数据按 IP 子网IPv4 或 IPv6建立索引常用于 GeoIP 地理定位。Reader 库负责打开.mmdb文件、按 IP 查找记录并解码为 PHP 数据结构。YOURLS 即通过该生态在 functions-geo.php 中实例化\GeoIp2\Database\Reader读取includes/geo/GeoLite2-Country.mmdb从而把访问者 IP 转换为两位国家代码如US、FR。从仓库依赖看YOURLS 的 composer.json 声明了geoip2/geoip2 : ^2.10其底层正是本 README 所描述的maxmind-db/reader纯 PHP 实现。安装方式方式一C 扩展性能推荐对于高频 IP 查询场景官方推荐通过 PIEPHP Installer for Extensions安装 C 扩展pie install maxmind-db/reader-ext该扩展依赖 MaxMind 的 C 语言库 libmaxminddb需要按所在平台先完成安装Debian 系可安装php5-devRedHat/Fedora 系可安装php-devel等开发包。方式二纯 PHP 实现Composer免编译不需要编译任何 C 代码兼容性最好。步骤如下在项目根目录下载 Composercurl -sS https://getcomposer.org/installer | php执行后项目目录中会出现composer.phar。安装依赖php composer.phar require maxmind-db/reader:^1.13.1执行后项目目录会新增composer.json、composer.lock以及vendor目录若使用版本控制系统应将composer.json纳入版本管理。在代码中引入 Composer 自动加载器require vendor/autoload.php;方式三Standalone 免 Composer若不想使用 Composer库根目录提供了自定义的autoload.php直接包含即可require(/path/to/MaxMind-DB-Reader-php/autoload.php);随后正常实例化读取器use MaxMind\Db\Reader; $reader new Reader(example.mmdb);方式四RPM 包Fedora 系官方 Fedora 仓库提供php-maxminddb包# Fedora dnf install php-maxminddb # CentOS / RHEL 7先启用 EPEL 仓库再执行 yum install php-maxminddb需要提醒的是这些 RPM 包并非由 MaxMind 维护。核心用法示例README 给出的最小可运行示例?php require_once vendor/autoload.php; use MaxMind\Db\Reader; $ipAddress 24.24.24.24; $databaseFile GeoIP2-City.mmdb; $reader new Reader($databaseFile); // get 仅返回该 IP 对应的记录 print_r($reader-get($ipAddress)); // getWithPrefixLen 返回数组记录 该记录关联的网络前缀长度 print_r($reader-getWithPrefixLen($ipAddress)); $reader-close();两个查询方法的区别在于get(string $ipAddress)返回记录本体找不到时返回nullgetWithPrefixLen(string $ipAddress)返回[record, prefixLen]两元素数组prefixLen即该 IP 命中的网段前缀长度CIDR 位宽可用于了解命中的是多大范围的网段。从源码看get()内部就是解包getWithPrefixLen()的第一个元素因此两者共享同一查询链路。用完后务必调用close()释放文件句柄对已关闭的库再调用查询方法会抛出BadMethodCallExceptionAttempt to read from a closed MaxMind DB.见 Reader.php。元数据访问Reader::metadata()返回一个Metadata对象克隆副本可读取binaryFormatMajorVersion、ipVersion、nodeCount、recordSize、buildEpoch、databaseType等字段。从 Metadata.php 的构造函数可见这些字段均来自数据库元数据区块且nodeByteSize recordSize / 4、searchTreeSize nodeCount * nodeByteSize——这正是后面检索树定位的关键参数。可选 C 扩展三种安装路径C 扩展是MaxMind\Db\Reader的即插即用替代实现drop-in replacement。只要装了自动加载器业务代码无需任何改动两个实现暴露相同 API。PIE推荐pie install maxmind-db/reader-extPECL传统方式先安装 libmaxminddb再执行pecl install maxminddb源码编译在发行包顶层目录执行cd ext phpize ./configure make make test sudo make install然后在php.ini中加载扩展extensionmaxminddb.so128 位无符号整数支持MaxMind DB 格式原生包含 128 位无符号整数类型。虽然当前 MaxMind 发行的数据库尚未使用该类型但纯 PHP Reader 与 C 扩展均已支持纯 PHP Reader 读取包含 128 位整数的数据库时必须依赖 gmp 或 bcmath 扩展返回值表示方式有差异C 扩展返回带0x前缀的十六进制字符串纯 PHP Reader 返回无前缀的十进制字符串官方声明未来统一两种实现的返回格式十六进制或十进制不视为破坏性变更。从 Decoder.php 的 decodeUint 实现可以看到具体逻辑当整数能放进 PHP 原生 int 时直接移位累加超出时若装了 gmp 则用gmp_mul/gmp_add逐字节构造十进制字符串否则回退 bcmath两者都不可用时抛出RuntimeExceptionThe gmp or bcmath extension must be installed to read this database.。这条异常路径与 README 的 Requirements 章节完全对应。环境要求PHP 7.2 及以上使用纯 PHP API 读取某些数据库含 128 位整数时可能需要 GMP 或 BCMath 扩展。从源码看查询原理纵深解析虽然 README 未深入实现细节但结合源码可以梳理出完整的查询链路理解这些有助于排查InvalidDatabaseException等异常。文件加载与元数据定位构造Reader时Reader.php传入目录路径会直接抛出InvalidDatabaseException与 C 扩展行为一致文件不可读抛出InvalidArgumentException通过findMetadataStart()在文件末尾最多 128 KiBMETADATA_MAX_SIZE 131072范围内反向扫描魔数标记\xAB\xCD\xEFMaxMind.comReader.php找到后解码元数据解码器以searchTreeSize 16数据段分隔符大小为指针基址构造并计算 IPv4 起始节点ipV4StartNode()。检索树遍历getWithPrefixLen()内部调用findAddressInTree()Reader.php用inet_pton()把 IP 字符串转为二进制非法 IP 抛出InvalidArgumentException逐位遍历二叉树从节点 0 开始按 IP 的每一位读取左右子节点readNode()支持 24/28/32 三种 record size 布局Reader.phpIPv6 数据库中查询 IPv4 地址时可直接跳过前 96 个节点从ipV4Start开始反过来在 IPv4-only 数据库中查 IPv6 地址则直接抛异常遍历结束的三种结果节点数等于nodeCount表示记录为空返回[0, prefixLen]大于nodeCount表示命中数据指针否则判定数据库损坏。数据指针解析resolveDataPointer()Reader.php把指针换算为数据段绝对偏移pointer - nodeCount searchTreeSize偏移越过文件大小时抛出The MaxMind DB files search tree is corrupt——这正是 YOURLS 的 functions-geo.php 注释中记录的InvalidDatabaseException典型场景。随后交给Decoder解码。数据类型解码Decoder.php 实现了完整的 MaxMind DB 类型系统控制字节高 3 位表示类型map、array、boolean、utf8 string、bytes、double、float、int32、uint16/32/64/128 等低 5 位表示尺寸29/30/31 时需额外读取扩展字节见sizeFromCtrlByte()map/array 递归解码pointer 类型则跳转后跟随引用。Util::read()通过fseek/fread/ftell严格校验读取字节数不足即抛The MaxMind DB file contains bad dataUtil.php。YOURLS 中的落地实践YOURLS 把 GeoLite2 数据库放在 includes/geo/GeoLite2-Country.mmdb其 GeoIP 包说明 提示如需手动更新数据库可在 maxmind.com 注册账号后替换该文件。核心入口是 yourls_geo_ip_to_countrycode()优先读取 Cloudflare 的HTTP_CF_IPCOUNTRY头若启用geo_use_cloudflare过滤器且值形如两位大写字母数据库路径可通过geo_ip_path_to_db过滤器替换默认YOURLS_INC./geo/GeoLite2-Country.mmdb不可读时返回默认值实例化\GeoIp2\Database\Reader后调用country($ip)取得$record-country-isoCode如US捕获所有\Exception并返回$default涵盖AddressNotFoundExceptionIP 不在库中、InvalidArgumentExceptionIP 非法或库不可读、InvalidDatabaseException库损坏等插件可通过shunt_geo_ip_to_countrycode过滤器整体短路该逻辑。得到两位国家码后yourls_geo_countrycode_to_countryname() 可映射为完整国名yourls_geo_get_flag() 则输出 includes/geo/flags 目录下对应的国旗图片 URL。这也解释了仓库内flag_*.gif文件群的用途。常见异常速查异常触发条件错误消息示例InvalidDatabaseException传入目录、文件损坏、搜索树损坏Error opening database file (...) Is this a valid MaxMind DB file?、The MaxMind DB files search tree is corruptInvalidArgumentException文件不存在/不可读、IP 非法The file ... does not exist or is not readable.、The value 10.0.0.300 is not a valid IP address.BadMethodCallException对已 close 的库执行查询Attempt to read from a closed MaxMind DB.RuntimeException需 128 位整数但缺 gmp/bcmathThe gmp or bcmath extension must be installed to read this database.版本策略与许可项目采用语义化版本Semantic Versioning本软件 Copyright (c) 2014-2025 by MaxMind, Inc.基于 Apache License 2.0 开源若在 YOURLS 中使用 GeoLite2 数据还需遵守 MaxMind GeoLite2 EULA详见 includes/geo/README.md。参考文件索引官方 READMEincludes/vendor/maxmind-db/reader/README.md读取器实现Reader.php解码器实现Decoder.php元数据模型Metadata.php文件读取工具Util.php异常类型InvalidDatabaseException.phpYOURLS 地理定位封装includes/functions-geo.phpGeoLite2 数据与说明includes/geo/README.md赞分享后端【免费下载链接】YOURLS The standard, self hosted, powerful and customizable, URL shortener in PHP项目地址https://gitcode.com/gh_mirrors/yo/YOURLS点击查看免费下载相关推荐MaxMind DB Reader PHP 项目教程MaxMind DB Reader PHP 项目教程 1. 项目的目录结构及介绍 MaxMind DB Reader PHP 项目的目录结构相对简单主要包含以数据库后端探索MaxMind DB Reader PHP API高效解析IP数据的利器探索MaxMind DB Reader PHP API高效解析IP数据的利器 项目简介 MaxMind DB Reader PHP API 是一个专为PHP数据库后端MaxMind DB Reader for PHP 使用教程MaxMind DB Reader for PHP 使用教程 项目介绍 MaxMind DB Reader for PHP 是一个用于读取 MaxMind DB数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 YOURLS 中的 MaxMind DB Reader PHP API 完全指南：从安装、查询到源码级解析
后端【免费下载链接】YOURLS The standard, self hosted, powerful and customizable, URL shortener in PHP项目地址https://gitcode.com/gh_mirrors/yo/YOURLS点击查看免费下载导读MaxMind DB 是一种以 IP 网段IPv4 或 IPv6为索引的二进制数据库格式MaxMind DB Reader PHP API 则是读取该格式的标准 PHP 客户端。本文以 YOURLS 仓库内 maxmind-db/reader 的 README 为主体结合 Reader.php、Decoder.php 等源码系统讲解安装方式、核心 API 用法、C 扩展加速方案、128 位整数支持与底层查询原理并说明 YOURLS 是如何利用该生态实现 IP 到国家/地区定位的。读完本文你将能够独立完成 MaxMind DB 读取环境的搭建与 IP 地理定位查询并理解其二进制检索树的实现细节。MaxMind DB 格式与 Reader 库定位MaxMind DB 是一个二进制文件格式数据按 IP 子网IPv4 或 IPv6建立索引常用于 GeoIP 地理定位。Reader 库负责打开.mmdb文件、按 IP 查找记录并解码为 PHP 数据结构。YOURLS 即通过该生态在 functions-geo.php 中实例化\GeoIp2\Database\Reader读取includes/geo/GeoLite2-Country.mmdb从而把访问者 IP 转换为两位国家代码如US、FR。从仓库依赖看YOURLS 的 composer.json 声明了geoip2/geoip2 : ^2.10其底层正是本 README 所描述的maxmind-db/reader纯 PHP 实现。安装方式方式一C 扩展性能推荐对于高频 IP 查询场景官方推荐通过 PIEPHP Installer for Extensions安装 C 扩展pie install maxmind-db/reader-ext该扩展依赖 MaxMind 的 C 语言库 libmaxminddb需要按所在平台先完成安装Debian 系可安装php5-devRedHat/Fedora 系可安装php-devel等开发包。方式二纯 PHP 实现Composer免编译不需要编译任何 C 代码兼容性最好。步骤如下在项目根目录下载 Composercurl -sS https://getcomposer.org/installer | php执行后项目目录中会出现composer.phar。安装依赖php composer.phar require maxmind-db/reader:^1.13.1执行后项目目录会新增composer.json、composer.lock以及vendor目录若使用版本控制系统应将composer.json纳入版本管理。在代码中引入 Composer 自动加载器require vendor/autoload.php;方式三Standalone 免 Composer若不想使用 Composer库根目录提供了自定义的autoload.php直接包含即可require(/path/to/MaxMind-DB-Reader-php/autoload.php);随后正常实例化读取器use MaxMind\Db\Reader; $reader new Reader(example.mmdb);方式四RPM 包Fedora 系官方 Fedora 仓库提供php-maxminddb包# Fedora dnf install php-maxminddb # CentOS / RHEL 7先启用 EPEL 仓库再执行 yum install php-maxminddb需要提醒的是这些 RPM 包并非由 MaxMind 维护。核心用法示例README 给出的最小可运行示例?php require_once vendor/autoload.php; use MaxMind\Db\Reader; $ipAddress 24.24.24.24; $databaseFile GeoIP2-City.mmdb; $reader new Reader($databaseFile); // get 仅返回该 IP 对应的记录 print_r($reader-get($ipAddress)); // getWithPrefixLen 返回数组记录 该记录关联的网络前缀长度 print_r($reader-getWithPrefixLen($ipAddress)); $reader-close();两个查询方法的区别在于get(string $ipAddress)返回记录本体找不到时返回nullgetWithPrefixLen(string $ipAddress)返回[record, prefixLen]两元素数组prefixLen即该 IP 命中的网段前缀长度CIDR 位宽可用于了解命中的是多大范围的网段。从源码看get()内部就是解包getWithPrefixLen()的第一个元素因此两者共享同一查询链路。用完后务必调用close()释放文件句柄对已关闭的库再调用查询方法会抛出BadMethodCallExceptionAttempt to read from a closed MaxMind DB.见 Reader.php。元数据访问Reader::metadata()返回一个Metadata对象克隆副本可读取binaryFormatMajorVersion、ipVersion、nodeCount、recordSize、buildEpoch、databaseType等字段。从 Metadata.php 的构造函数可见这些字段均来自数据库元数据区块且nodeByteSize recordSize / 4、searchTreeSize nodeCount * nodeByteSize——这正是后面检索树定位的关键参数。可选 C 扩展三种安装路径C 扩展是MaxMind\Db\Reader的即插即用替代实现drop-in replacement。只要装了自动加载器业务代码无需任何改动两个实现暴露相同 API。PIE推荐pie install maxmind-db/reader-extPECL传统方式先安装 libmaxminddb再执行pecl install maxminddb源码编译在发行包顶层目录执行cd ext phpize ./configure make make test sudo make install然后在php.ini中加载扩展extensionmaxminddb.so128 位无符号整数支持MaxMind DB 格式原生包含 128 位无符号整数类型。虽然当前 MaxMind 发行的数据库尚未使用该类型但纯 PHP Reader 与 C 扩展均已支持纯 PHP Reader 读取包含 128 位整数的数据库时必须依赖 gmp 或 bcmath 扩展返回值表示方式有差异C 扩展返回带0x前缀的十六进制字符串纯 PHP Reader 返回无前缀的十进制字符串官方声明未来统一两种实现的返回格式十六进制或十进制不视为破坏性变更。从 Decoder.php 的 decodeUint 实现可以看到具体逻辑当整数能放进 PHP 原生 int 时直接移位累加超出时若装了 gmp 则用gmp_mul/gmp_add逐字节构造十进制字符串否则回退 bcmath两者都不可用时抛出RuntimeExceptionThe gmp or bcmath extension must be installed to read this database.。这条异常路径与 README 的 Requirements 章节完全对应。环境要求PHP 7.2 及以上使用纯 PHP API 读取某些数据库含 128 位整数时可能需要 GMP 或 BCMath 扩展。从源码看查询原理纵深解析虽然 README 未深入实现细节但结合源码可以梳理出完整的查询链路理解这些有助于排查InvalidDatabaseException等异常。文件加载与元数据定位构造Reader时Reader.php传入目录路径会直接抛出InvalidDatabaseException与 C 扩展行为一致文件不可读抛出InvalidArgumentException通过findMetadataStart()在文件末尾最多 128 KiBMETADATA_MAX_SIZE 131072范围内反向扫描魔数标记\xAB\xCD\xEFMaxMind.comReader.php找到后解码元数据解码器以searchTreeSize 16数据段分隔符大小为指针基址构造并计算 IPv4 起始节点ipV4StartNode()。检索树遍历getWithPrefixLen()内部调用findAddressInTree()Reader.php用inet_pton()把 IP 字符串转为二进制非法 IP 抛出InvalidArgumentException逐位遍历二叉树从节点 0 开始按 IP 的每一位读取左右子节点readNode()支持 24/28/32 三种 record size 布局Reader.phpIPv6 数据库中查询 IPv4 地址时可直接跳过前 96 个节点从ipV4Start开始反过来在 IPv4-only 数据库中查 IPv6 地址则直接抛异常遍历结束的三种结果节点数等于nodeCount表示记录为空返回[0, prefixLen]大于nodeCount表示命中数据指针否则判定数据库损坏。数据指针解析resolveDataPointer()Reader.php把指针换算为数据段绝对偏移pointer - nodeCount searchTreeSize偏移越过文件大小时抛出The MaxMind DB files search tree is corrupt——这正是 YOURLS 的 functions-geo.php 注释中记录的InvalidDatabaseException典型场景。随后交给Decoder解码。数据类型解码Decoder.php 实现了完整的 MaxMind DB 类型系统控制字节高 3 位表示类型map、array、boolean、utf8 string、bytes、double、float、int32、uint16/32/64/128 等低 5 位表示尺寸29/30/31 时需额外读取扩展字节见sizeFromCtrlByte()map/array 递归解码pointer 类型则跳转后跟随引用。Util::read()通过fseek/fread/ftell严格校验读取字节数不足即抛The MaxMind DB file contains bad dataUtil.php。YOURLS 中的落地实践YOURLS 把 GeoLite2 数据库放在 includes/geo/GeoLite2-Country.mmdb其 GeoIP 包说明 提示如需手动更新数据库可在 maxmind.com 注册账号后替换该文件。核心入口是 yourls_geo_ip_to_countrycode()优先读取 Cloudflare 的HTTP_CF_IPCOUNTRY头若启用geo_use_cloudflare过滤器且值形如两位大写字母数据库路径可通过geo_ip_path_to_db过滤器替换默认YOURLS_INC./geo/GeoLite2-Country.mmdb不可读时返回默认值实例化\GeoIp2\Database\Reader后调用country($ip)取得$record-country-isoCode如US捕获所有\Exception并返回$default涵盖AddressNotFoundExceptionIP 不在库中、InvalidArgumentExceptionIP 非法或库不可读、InvalidDatabaseException库损坏等插件可通过shunt_geo_ip_to_countrycode过滤器整体短路该逻辑。得到两位国家码后yourls_geo_countrycode_to_countryname() 可映射为完整国名yourls_geo_get_flag() 则输出 includes/geo/flags 目录下对应的国旗图片 URL。这也解释了仓库内flag_*.gif文件群的用途。常见异常速查异常触发条件错误消息示例InvalidDatabaseException传入目录、文件损坏、搜索树损坏Error opening database file (...) Is this a valid MaxMind DB file?、The MaxMind DB files search tree is corruptInvalidArgumentException文件不存在/不可读、IP 非法The file ... does not exist or is not readable.、The value 10.0.0.300 is not a valid IP address.BadMethodCallException对已 close 的库执行查询Attempt to read from a closed MaxMind DB.RuntimeException需 128 位整数但缺 gmp/bcmathThe gmp or bcmath extension must be installed to read this database.版本策略与许可项目采用语义化版本Semantic Versioning本软件 Copyright (c) 2014-2025 by MaxMind, Inc.基于 Apache License 2.0 开源若在 YOURLS 中使用 GeoLite2 数据还需遵守 MaxMind GeoLite2 EULA详见 includes/geo/README.md。参考文件索引官方 READMEincludes/vendor/maxmind-db/reader/README.md读取器实现Reader.php解码器实现Decoder.php元数据模型Metadata.php文件读取工具Util.php异常类型InvalidDatabaseException.phpYOURLS 地理定位封装includes/functions-geo.phpGeoLite2 数据与说明includes/geo/README.md赞分享后端【免费下载链接】YOURLS The standard, self hosted, powerful and customizable, URL shortener in PHP项目地址https://gitcode.com/gh_mirrors/yo/YOURLS点击查看免费下载相关推荐MaxMind DB Reader PHP 项目教程MaxMind DB Reader PHP 项目教程 1. 项目的目录结构及介绍 MaxMind DB Reader PHP 项目的目录结构相对简单主要包含以数据库后端探索MaxMind DB Reader PHP API高效解析IP数据的利器探索MaxMind DB Reader PHP API高效解析IP数据的利器 项目简介 MaxMind DB Reader PHP API 是一个专为PHP数据库后端MaxMind DB Reader for PHP 使用教程MaxMind DB Reader for PHP 使用教程 项目介绍 MaxMind DB Reader for PHP 是一个用于读取 MaxMind DB数据库后端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考