如何为PhpUserAgent添加新浏览器支持？从正则修改到测试数据与常量生成的完整开发者指南

如何为PhpUserAgent添加新浏览器支持从正则修改到测试数据与常量生成的完整开发者指南【免费下载链接】PhpUserAgentLightning Fast, Minimalist PHP User Agent String Parser.项目地址: https://gitcode.com/gh_mirrors/ph/PhpUserAgentPhpUserAgent 是一个极速、极简的 PHP User-Agent 解析库核心代码不到 200 行只靠三条正则表达式就能识别所有主流浏览器。本文带你走通「为 PhpUserAgent 添加新浏览器支持」的完整流程修改浏览器正则、补充测试数据、用make generate自动生成浏览器常量最后跑通 PHPUnit 测试一次讲清。为什么PhpUserAgent的浏览器识别这么容易扩展PhpUserAgent 的解析逻辑全部集中在一个文件里核心解析函数src/UserAgentParser.php浏览器常量定义src/UserAgent/Browsers.php自动生成禁止手改测试数据源tests/user_agents.dist.json常量生成脚本bin/constant_generator.php解析函数内部有两大段正则src/UserAgentParser.php正则作用位置平台正则从 UA 括号内提取操作系统src/UserAgentParser.php第 64-70 行浏览器正则匹配浏览器名与版本号src/UserAgentParser.php第 98-108 行浏览器正则是一个「名称白名单」例如Camino|Kindle(\ Fire)?|Firefox|…|Vivaldi|…。想支持新浏览器本质上就是把这个白名单加上新名字再为它配上测试用例。一键准备工作克隆仓库并验证测试基线git clone https://gitcode.com/gh_mirrors/ph/PhpUserAgent cd PhpUserAgent composer install make testmake test会执行 PHPUnit 全量测试见Makefile第 2-3 行。动手前先确认基线全绿改动后才能分辨失败是不是你造成的。环境要求PHP 5.4 及 ext-ctype见composer.json。第一步修改浏览器正则把新浏览器加入白名单以假想的新浏览器CoolBrowser为例打开src/UserAgentParser.php在浏览器正则的名称列表中追加它约第 99-104 行%(?Pprev.)?(?PbrowserCamino|…|Whale|CoolBrowser| Applebot|Facebot|…)%ix三条小技巧项目贡献规范同样要求「够简短、够聪明」能合并就合并用交替组EdgA?同时覆盖Edg和EdgA用(?:Headless)?Chrome覆盖Chrome与HeadlessChrome。区分大小写时用(?-i:…)如(?-i:Edge)避免误伤小写的edge词。保持imx标志位x表示允许正则中换行与注释正是这份代码保持可读的关键。第二步处理 UA 别名与特殊版本来源很多浏览器的 UA 令牌和真实名字不一样或版本号藏在别处。PhpUserAgent 用一个别名映射表解决位于src/UserAgentParser.php第 184 行附近$findT([ OPR Opera, UCBrowser UC Browser, CriOS Chrome, … ] )如果你的新浏览器 UA 里写的是缩写比如令牌CBL代表CoolBrowser就在这里加一条CBL CoolBrowser。还要检查版本号的提取正则中(?Pversion[0-9A-Z.])会抓取紧跟在浏览器名后的版本。若新浏览器把版本写在Version/字段类似 Safari 的写法则需参考 Opera 分支第 201-203 行的写法补一段判断。第三步在测试数据中为新浏览器添加UA样本测试数据是一份「UA 字符串 → 期望结果」的 JSON位于tests/user_agents.dist.json现有 2000 行按浏览器字母排序。为新浏览器追加样本Mozilla/5.0 (Windows NT 10.0; Win64; x64) CoolBrowser/1.2.3: { platform: Windows, browser: CoolBrowser, version: 1.2.3 }, Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) CoolBrowser/1.2.3: { platform: Macintosh, browser: CoolBrowser, version: 1.2.3 }关键细节覆盖每个平台贡献指南CONTRIBUTING.md明确要求尽量为浏览器所在的每一个平台都加测试 UA否则合并会很慢。本地覆盖技巧测试脚本tests/UserAgentParserFunctionTest.php第 13-30 行优先读取tests/user_agents.json不存在时才用user_agents.dist.json。开发时可以先make clean生成空文件本地只放新浏览器的样本快速迭代。分类一致性tests/ClassConsistencyTest.php会校验同一浏览器名在所有样本中分类Browsers / Bots一致若新令牌同时命中 Bots 与 Browsers 两个清单需在 JSON 中用class: [Bots, Browsers]标注。第四步一条命令完成常量生成不要手改src/UserAgent/Browsers.php—— 文件头部明确写着 DO NOT EDIT THIS FILE - IT IS GENERATED BY constant_generator.php。正确姿势是运行 Makefile 里的generate目标make generate它实际执行两件事Makefile第 10-13 行bin/user_agent_sorter.php把测试数据排序后重写tests/user_agents.dist.jsonbin/constant_generator.php扫描测试数据中出现的浏览器名重新生成src/UserAgent/Browsers.php、Bots.php、Platforms.php三个常量接口。生成后你的新浏览器会自动获得Browsers::COOLBROWSER CoolBrowser这样的常量业务代码即可if( $ua-browser() Browsers::COOLBROWSER )精确判断。✅运行完整测试make test 全绿才算完成make test # 等价于 ./vendor/bin/phpunit --coverage-text测试通过需同时满足UserAgentParserFunctionTest每条 JSON 样本解析结果与期望一致UserAgentParserObjectTest面向对象封装UserAgentParser::parse()行为一致ClassConsistencyTest浏览器分类无冲突。另外别忘了代码风格红线CONTRIBUTING.md缩进必须用Tab、代码要简短精炼、提交前自查是否误伤了其他浏览器的匹配。常见误区与注意事项误区正确做法为已停产的老浏览器加支持项目明确只支持现代浏览器死浏览器不必追尝试从 UA 识别操作系统版本这是被明确拒绝的功能UA 中的 OS 版本不可靠期望识别 Brave 等伪装浏览器Brave 刻意使用与 Chrome 完全相同的 UA设计上无法区分手工编辑Browsers.php常量一律通过make generate生成总结新浏览器支持的四步闭环改正则src/UserAgentParser.php的浏览器白名单加新名字必要时补别名映射加测试tests/user_agents.dist.json中为每个平台补 UA 样本生成常量make generate自动重写src/UserAgent/Browsers.php跑测试make test全绿后提交 Pull Request。整个流程改动面小、可验证性强这正是 PhpUserAgent「小于 200 行代码」的极简设计带来的红利——新人也能在半天内完成一个新浏览器的完整支持。【免费下载链接】PhpUserAgentLightning Fast, Minimalist PHP User Agent String Parser.项目地址: https://gitcode.com/gh_mirrors/ph/PhpUserAgent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考