PHP 8.5 URI 扩展怎样解析标准 URL

我第一次把 PHP 8.5 的 URI 扩展放进 URL 处理代码时，最先改掉的不是某一行语法，而是“所有 URL 都用同一种解析规则”的习惯。结论很明确：需要 RFC 3986 语义时使用 Uri\Rfc3986\Uri，用 parse() 做可恢复的解析，用构造器做严格创建；需要浏览器 URL 语义时再选择 Uri\WhatWg\Url。不要把新对象直接当成 parse_url() 返回数组的同名替代品。

官方文档：https://www.php.net/manual/en/book.uri.php

先把 parse_url 与 PHP 8.5 URI 扩展分开

parse_url() 适合快速拆出数组字段，历史代码迁移成本低；PHP 8.5 的 URI 扩展则把 URI 表达成对象，并提供标准化组件读取、重新组合和修改能力。它关注的是“这个字符串能否按某套规范被理解”，而不仅是尽量从字符串里切出几个片段。

这一区分很重要：RFC 3986 允许相对 URI，WHATWG URL 面向带 scheme 的 URL，并会执行更多浏览器式转换。接口名已经把两套语义分开，业务代码应在入口处确定规范，而不是解析完后再猜结果。

用 parse 或构造器读取 URL 组件

外部输入、配置文件或用户提交的地址通常先用静态 parse()。它把失败表达为 null，适合在业务层返回校验错误。已经确定必须是合法 URI 的内部配置，则可以直接使用构造器，让异常进入统一错误处理。

getScheme(), PHP_EOL;
echo $uri->getHost(), PHP_EOL; // 读取规范化后的主机组件。
echo $uri->getPath(), PHP_EOL;
echo $uri->getQuery(), PHP_EOL;

try {
    // 内部必须成立的 URI 可以用构造器获得严格失败信号。
    $trusted = new Uri('https://api.example.test/v1/items');
    echo $trusted->toString(), PHP_EOL;
} catch (InvalidUriException $e) {
    // 生产代码应记录上下文，但不要把原始敏感 URL 写进公开日志。
    echo '内部 URI 配置无效';
}

这里的 getHost()、getPath() 和 getQuery() 是对象读取入口；若要保留输入中的原始编码形式，应区分普通 getter 与对应的 raw getter。输出整条地址时使用 toString()，不要依赖对象被隐式转换成字符串。

用不可变 with 方法生成修改后的地址

URI 对象适合放进请求构造或路由适配层，因为修改方法返回新对象，原对象不会被悄悄改写。对我来说，这比在数组中反复覆盖 path、query 更容易追踪：基础地址可以复用，分页或版本路径在局部生成。

withPath('/v2/items')
        ->withQuery('page=3&limit=20');

    echo $base->toString(), PHP_EOL;
    echo $next->toString(), PHP_EOL;
} catch (InvalidUriException $e) {
    // 路径或查询组合不合法时，把错误交给调用方处理。
    echo '修改后的 URI 无效';
}

查询参数仍然是 URI 的 query 字符串，不是自动生成的 PHP 数组。需要增删单个参数时，先用业务层明确编码规则，再把最终字符串交给 withQuery()；不要把 URL 编码和业务参数拼接混在多处。

相对引用与规范化边界要提前定下来

资源链接经常不是完整 URL，例如 ../assets/app.css。这时先创建绝对基准 URI，再调用 resolve()。不要把相对字符串直接交给需要完整 URL 的下游客户端，也不要用字符串替换模拟路径合并。

resolve('../assets/app.css');
echo $asset->toString(), PHP_EOL;

最终迁移时保留一张小表就够了：

常见问题

PHP 8.5 URI 扩展能完全替换 parse_url() 吗？

不能机械替换。旧代码若只需要数组拆分，parse_url() 仍可保留；需要标准校验、对象修改或相对引用解析时，再迁移到 URI 对象。

parse() 和 new Uri() 该怎么选？

不希望异常穿透业务边界时用 parse()；内部配置必须合法、失败应进入异常处理时用构造器。

为什么 RFC 3986 和 WHATWG URL 要分开？

两套规范对相对 URI、主机大小写和自动转换的处理不同。先按业务边界选解析器，再统一下游的序列化格式。

我会把迁移顺序固定为“确定规范、选择失败信号、读取组件、最后修改和序列化”。这样 PHP 8.5 URI 扩展带来的收益是可控的对象化处理，而不是把旧的字符串拼接问题换一个类名继续保留。