PHP 8.5 URI extension新增 URI 能力适合替换哪些代码

我在维护 PHP 项目的 URL 代码时，最容易遇到的不是“不会取 host”，而是同一个字符串在不同调用方眼里有不同语义：有的接口允许相对 URI，有的接口必须遵循浏览器规则，还有一些旧代码只是用正则判断“看起来像 URL”。PHP 8.5 的 URI extension 正好把这些职责拆成了更明确的标准 API，但它不是把所有 parse_url() 机械替换掉。

适合迁移的是“需要按标准解析、校验、规范化、解析相对引用或不可变修改”的代码；只需要兼容历史数组返回值的地方，可以先保留旧实现。选择时先问清楚输入是 RFC 3986 URI，还是浏览器语义下的 WHATWG URL。

官方地址：https://www.php.net/manual/en/book.uri.php

本文按一个实际迁移顺序展开：先分组旧代码，再选择实现，最后处理异常、组件修改和上线兼容性。PHP 8.5 URI extension 的事实依据来自 PHP 官方发布说明、URI 手册和 URL Parsing API RFC。

哪些旧代码适合先替换

不要从全局搜索到 parse_url 就批量改。更稳妥的做法是先把旧代码按职责分成四组：读取组件、判断输入是否合法、拼接或修改 URI、把相对引用套到基准地址上。

这里最值得先迁移的是边界敏感的代码：例如回调地址白名单、反向代理传入的绝对地址、需要解析相对引用的资源地址，以及会反复修改 host 或 path 的链接构造器。它们一旦继续依赖正则和字符串拼接，问题通常不会在普通样例中暴露，而会出现在编码、默认端口或相对路径上。

RFC 3986 和 WHATWG URL 应该选哪一个

PHP 8.5 提供两个不同命名空间的实现，分开命名是为了让代码直接表达采用的规范。Uri\Rfc3986\Uri 面向 RFC 3986 URI；它能处理没有 scheme 的相对 URI，也更适合需要保留 URI 原始结构、再按 RFC 规则规范化的场景。Uri\WhatWg\Url 面向 WHATWG URL，适合必须贴近浏览器如何处理 URL 的场景。

一个简单的判断表是：

两者都不是安全策略本身。URI 类可以帮助你正确拆解和规范化输入，但“这个 host 是否允许”“是否只能使用 HTTPS”“是否允许用户信息”仍然属于业务规则。

解析和校验怎么替换 parse_url 与正则

在接收不可信输入时，优先考虑静态 parse() 工厂方法。解析成功时它返回 URI 对象，解析失败时返回 null，业务层可以把失败转换成 400 响应或表单错误，而不是依赖字符串是否为空。

getScheme() !== 'https' || $uri->getHost() !== 'example.com') {
    throw new DomainException('callback URL 不在允许范围内');
}

echo $uri->toAsciiString();

如果调用方更适合异常流程，可以使用构造函数。构造函数和 with*、resolve() 等操作在失败时会抛出 URI 异常；这适合已经有统一异常处理中间件的服务，但不适合把用户输入直接当成“必定合法”的值。

和旧的 parse_url() 相比，新 API 的关键改变不是返回数组变成对象，而是让规范选择和失败语义显式化。迁移时应把原来“数组键不存在”的分支改成“解析失败、组件为空或业务白名单不通过”的分支。

相对引用、组件修改和字符串拼接怎么迁移

很多项目会用 rtrim($base, '/') . '/' . ltrim($path, '/') 生成链接。这个做法对简单路径有效，但一旦出现 ..、查询串、片段或百分号编码，调用方就开始承担 URI 解析器的工作。PHP 8.5 可以把基准 URI 和相对引用交给 resolve()。

resolve('../assets/app.js');

// 输出时显式选择规范化后的字符串表示。
echo $resource->toString();

URI 对象是只读的，修改 host 或 path 时不要期待原对象被原地改变，而要接住新对象：

withHost('api.example.com')
    ->withPath('/v2/orders');

// 只有在需要交给 HTTP 客户端或页面时才序列化成字符串。
echo $public->toString();

这种写法的收益是把“修改组件”和“重新拼接字符串”分开。它不会自动替你决定权限，也不会替你检查最终 URL 是否可以访问，但可以把分隔符和标准化逻辑集中在 URI 对象上。

哪些代码不建议立即替换

第一类是不在 PHP 8.5 运行环境中的共享包。如果库要同时支持 PHP 8.4 及更早版本，直接引用 URI 类会改变最低版本要求。可以先在应用层或兼容适配层引入，而不是把公共包的所有接口一次改掉。

第二类是依赖数组形状的旧接口。parse_url() 的返回值可能已经被缓存、序列化，或传给多个历史函数。把它改成对象不只是替换一行代码，还会影响类型声明、测试夹具和日志格式，应单独设计 DTO 或适配器。

第三类是已经由 PSR-7 或 HTTP 客户端对象管理的 URI。此时先确认对象的编码、不可变方法和规范选择，不要为了“使用新扩展”把一个稳定的第三方抽象强行换成 PHP 内置类。

第四类是安全策略不清楚的 URL 校验。URI extension 能比正则更可靠地解析输入，但最终的 scheme、host、端口、凭据和重定向策略仍然要由业务代码限制。解析正确不等于请求目标安全。

上线前保留一张迁移清单

我会把迁移拆成四个小提交：先添加规范选择和输入样例，再把纯解析函数换成 URI 对象，然后迁移相对引用和组件修改，最后删除确定没有调用方的正则和拼接辅助函数。每一步都能回滚，也容易定位行为变化。

• 确认生产 PHP 版本达到 8.5，并让 CI 使用同一主版本测试。
• 为绝对 URL、相对 URI、空字符串、非法字符、查询串和片段分别准备样例。
• 明确每个调用点采用 RFC 3986 还是 WHATWG，不要用“默认”代替选择。
• 把解析失败、白名单失败和网络请求失败分开记录。
• 如果外部库仍需要字符串或 PSR-7 对象，在边界处完成一次显式转换。

这样迁移的目标不是让所有 URL 代码都变成同一种写法，而是让每个调用点都能回答三个问题：输入遵循哪套规范、失败如何返回、业务允许什么结果。

常见问题

PHP 8.5 的 URI extension 能完全替代 parse_url() 吗？ 不能。它适合需要标准化、校验、相对引用解析或不可变修改的场景；只需要旧数组字段且兼容版本较低的代码可以暂时保留。

RFC 3986 和 WHATWG URL 最大的区别是什么？ 前者更适合 URI 和相对引用模型，后者更贴近浏览器 URL 处理。安全敏感代码应显式选择，不要混用两套结果。

parse() 和构造函数怎么选？ 面对用户输入或批量导入时，parse() 返回 null，便于把失败当成普通分支；内部已经建立异常流程的代码可以使用构造函数。

withHost() 会修改原来的 URI 吗？ 不会。URI 类是只读对象，with* 方法返回新对象，调用方必须接住返回值。