PHP Uri\WhatWg怎样处理浏览器风格的相对 URL

PHP 处理浏览器风格的相对 URL，可以使用 PHP 8.5 起提供的 Uri\WhatWg\Url：先把页面地址构造成基准 URL，再调用 resolve() 解析相对引用，最后用 toAsciiString() 获取完整地址。不要用域名加路径的字符串拼接代替解析，因为父目录、根路径、查询字符串和片段引用遵循不同规则。

Uri\WhatWg 是命名空间，实际使用的类名包含最后一段 Url。这套 API 面向 WHATWG URL 规则；如果业务协议明确要求 RFC 3986，应选择相应的 Uri\Rfc3986\Uri，先确定语义，再选择工具。

官方地址：https://www.php.net/

先按使用场景选择解析方式

假设一个文档管理项目需要把编辑器保存的图片引用转为可展示地址。正文中可能出现 ../media/chart.png，也可能只有 ?view=print。项目关心的是这些引用相对于页面地址的含义，而不只是把一个字符串拆成若干字段。

PHP 手册指出，parse_url() 不遵循某一个既定 URI/URL 标准，也不是 URL 有效性检查器。迁移时不应只是把数组字段访问换成对象方法，而应重新确认下游需要哪套解释方式。例如同一个输入如果在前端和后端分别由不同规则解释，字符层面的判断就可能与实际目标不一致。

把页面地址建成基准URL对象

下面使用虚构的文档页面与图片引用。示例只进行 URL 对象处理，没有请求网络，也没有在本文写作环境执行。

resolve('../media/chart.png');
    echo $image->toAsciiString();
} catch (InvalidUrlException $e) {
    // 交给调用方处理非法地址，不回退到字符串拼接
    throw new RuntimeException('文档链接无法解析', 0, $e);
}

按这些输入的解析规则，目标应为 https://docs.example.com/manual/media/chart.png。这是示例的预期地址，不是实测输出。index.html 所在目录是 /manual/setup/，父目录引用从这里向上一级，再取得 media/chart.png。

另一种入口是构造函数的第二个参数：new Url($reference, $base)。这里的 $base 应是 Url 对象，不要照搬浏览器 JavaScript 的写法直接传入第二个字符串。相对输入没有基准时不能被独立接受；完整绝对 URL 则不依赖这个基准。

对照相对引用与末尾斜杠

采用同一个基准 https://docs.example.com/manual/setup/index.html?lang=zh#top，可以按下表理解不同引用。表中地址是按规则推导的预期值，不是网站访问结果。

最容易误判的是基准末尾的斜杠。对 https://docs.example.com/manual/setup/ 解析 guide.html，目标在 /manual/setup/ 下；若基准为 https://docs.example.com/manual/setup，目标则位于 /manual/ 下。解析器不会先访问服务器来判断 setup 实际是文件还是目录。

因此，基准应来自业务中已经确定的页面地址。若 HTML 文档另有有效的基准地址约定，应先确定它，再交给 URL 解析器。类本身并不读取 HTML，也不会自动寻找文档中的基准元素。对于已有页面系统，应让前后端使用相同的基准来源。

把解析失败和业务拒绝分开

resolve() 在结果非法时抛出 InvalidUrlException。如果调用方更适合分支处理，可以使用静态 parse()：它成功时返回对象，失败时返回 null。两种接口都不意味着地址符合站内链接等业务约束。

getScheme() !== 'https'
        || $target->getAsciiHost() !== 'docs.example.com'
        || !in_array($target->getPort(), [null, 443], true)) {
        throw new DomainException('链接不属于允许的文档站');
    }

    return $target->toAsciiString();
}

这里先基于对象取得协议、主机和端口，再应用一个明确的站内范围规则。它只演示文档地址处理，不是完整的服务端抓取防护。如果后续功能会请求资源，还需要对跳转和实际连接等环节另行设计控制，不能把这个函数的返回值当成任意网络操作的安全凭证。

手册也提供软错误信息，用于了解解析过程中可恢复的问题。可解析与原样保留不是一回事；若业务需要审计用户原始输入，应另外保存原字符串，并避免把其中可能存在的身份信息直接输出到页面或日志。展示在 HTML 中时，URL 序列化也不能替代对应上下文的转义。

迁移旧代码时保留输入样本

先从项目里整理真实引用类型：普通文件名、父目录、根路径、查询、片段、完整 URL，以及历史异常输入。为每类写明基准和期望地址，再替换旧实现。不要靠发现输出不同就把结果拼回旧字符串；差异可能正说明旧代码依赖了不合适的规则。

对于 PHP 8.5 之前的环境，不能直接使用该内置类。应在部署要求中明确运行环境，或采用能够匹配所选标准的维护中实现，并对同一组输入样本核对语义。迁移决定应围绕调用方实际需要的规则，而不是仅追求类名更现代。

为什么相对路径没有基准就失败？

因为它缺少确定目标所需的上下文。先确定完整页面地址，再解析引用，而不是随意补上某个域名。

resolve 会修改原来的基准吗？

不会。它返回新的 URL 对象。批量处理同一页面的多个链接时，可以复用基准，并分别保存结果。

解析成功就说明目标存在吗？

不说明。URL 对象处理的是地址语义，既没有读取服务器上的文件，也没有确认远端服务是否可达。

官方资料：https://www.php.net/manual/en/class.uri-whatwg-url.php；https://www.php.net/manual/en/uri-whatwg-url.resolve.php；https://www.php.net/manual/en/uri-whatwg-url.construct.php；https://www.php.net/manual/en/uri-whatwg-url.parse.php；https://www.php.net/manual/en/function.parse-url.php。