PHP 8.5 URI 扩展处理 RFC 3986 地址的使用方法

PHP 8.5 已经内置 URI 扩展。需要按 RFC 3986 处理通用 URI 时，直接使用 Uri\Rfc3986\Uri；它把解析、规范化、相对引用解析和组件修改放在一个不可变对象里。要先记住一个边界：浏览器 URL 行为应选择 Uri\WhatWg\Url，不要把两套规则混用。

官方资料：https://www.php.net/manual/en/book.uri.php

先确认 PHP 8.5 使用的是哪套 URI 语义

URI 扩展属于 PHP 8.5 的内置能力，不需要像第三方 Composer 包那样单独安装。项目启动时可以做一次能力检查；业务代码则明确导入 RFC 3986 类，避免只写一个含糊的 URL 工具封装。

getHost();

这里的 Rfc3986 不是装饰性的命名空间。PHP 官方 RFC 明确把 RFC 3986 URI 与 WHATWG URL 分成两个实现，因为相对 URI、主机规范化和浏览器兼容处理的预期并不相同。

用 raw 与 normalized 两组 API 看清地址变化

处理签名、缓存键或审计记录时，常常既要保留输入原貌，又要拿到可比较的规范形式。RFC 3986 类的 getRawPath()、getRawQuery() 和 toRawString() 保留原始表示；getPath()、getQuery() 和 toString() 则返回规范化结果。

getRawPath());
printf("normalized path: %s\n", $uri->getPath());
printf("normalized uri: %s\n", $uri->toString());

示意结果是：原始路径仍包含 /a/../b/%7e，规范化路径会移除点段并解码未保留字符，结果接近 /b/~；规范化 URI 还会把 scheme 和 host 统一为小写。要做原文留痕，不能把 toString() 当作原始输入。

用 resolve 和 with 方法处理相对地址

文档、接口资源或分页链接经常返回相对引用。先建立可信的基准 URI，再调用 resolve()，比手工拼接斜杠更稳妥。对象是 readonly 的，withScheme()、withPath() 等方法不会原地改写。

resolve('../health?full=1');

// with* 也返回新对象；把返回值接住，原对象仍保持不变。
$secure = $resolved->withScheme('https')->withPath('/health');
echo $secure->toString();

如果要保留查询串，只修改路径即可；如果要清除查询和片段，可以显式传入 null。这种链式写法的关键不是语法漂亮，而是让每次修改都形成可测试的新值，避免共享对象被某个调用点悄悄改掉。

把无效输入分成异常路径和可选路径

对内部配置或已经过校验的地址，构造器能让错误尽早暴露；对用户提交的候选地址，parse() 返回 null 更方便走普通校验分支。

PHP 8.4 及更早版本没有这套类。跨版本项目应把解析器包在自己的接口后面：新环境使用 Uri\Rfc3986\Uri，旧环境继续采用既有实现，并在兼容层测试 raw、规范化和异常语义是否一致，而不是只判断类名是否存在。

常见 API 选择清单

常见问题

PHP 8.5 的 URI 扩展需要额外安装吗？

不需要单独安装；它是 PHP 8.5 的内置 URI 能力。部署时仍应确认实际运行的 PHP CLI、FPM 和容器镜像版本一致。

为什么 getPath 和 getRawPath 不一样？

前者返回 RFC 3986 规范化路径，后者保留原始路径表示。签名或审计要留痕时使用 raw，路由比较或标准输出时使用 normalized。

withPath 调用后原来的 URI 会被改掉吗？

不会。URI 类是只读对象，withPath() 返回新的 URI；不接返回值就不会得到修改后的结果。