PHP 8.5 UriUrl 怎样读取查询参数

PHP 8.5 的 URI 扩展已经把 URL 查询组件变成了对象方法。标题里的“UriUrl”可以先按这个搜索词理解，但实际写代码时要使用 PHP 官方类名：符合 RFC 3986 的 Uri\Rfc3986\Uri，或面向 WHATWG URL 的 Uri\WhatWg\Url。读取查询参数的最小路径是先创建对象，再调用 getQuery()；如果还要把键值对交给业务逻辑，再显式调用 parse_str()。

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

先区分 Uri\Rfc3986\Uri 与 Uri\WhatWg\Url

PHP 8.5 新增的 URI 扩展同时覆盖 RFC 3986 URI 和 WHATWG URL 两套规则。普通服务端接口如果只需要读取稳定的查询组件，可以先选择与现有协议一致的类，不要把两个类名拼成不存在的 Uri\Url。下面的示例使用 RFC 3986 类；如果业务更贴近浏览器 URL 处理，则把类名换成 Uri\WhatWg\Url，读取方法仍是 getQuery()。

getQuery 读取字符串后再拆成参数

getQuery() 只负责取出查询组件，并不直接返回关联数组。它返回规范化后的字符串；查询不存在时返回 null。因此代码应先判断返回值，再决定是否交给 parse_str()：

getQuery();

if ($query === null) {
    // 没有问号查询组件时，使用业务约定的默认筛选条件
    $params = [];
} else {
    // parse_str() 负责键值对解析，不属于 URI 对象的方法
    parse_str($query, $params);
}

var_dump($query, $params);
// string(21) "page=2&tag=php%2085"
// array(2) { ["page"]=> string(1) "2" ["tag"]=> string(6) "php 85" }
?>

这个例子里，getQuery() 的结果仍是字符串；parse_str() 才把它变为 page 和 tag 两个键。生产代码还应对白名单字段做类型转换，例如把页码限制为正整数，不要直接信任查询参数。

原始查询、空查询和非法输入的处理边界

如果日志、签名校验或审计需要看到用户最初提交的编码形式，应保存 getRawQuery() 的结果；如果只是做路由筛选，规范化后的 getQuery() 更适合作为后续解析输入。两者用途不同，不能靠字符串是否为空来替代这个判断。

用命令行做一次最小检查

 %s\n", $input, var_export($uri->getQuery(), true));
    } catch (Throwable $error) {
        // 非法输入进入这里，调用方可以返回 400 或记录排障信息
        printf("%s => invalid URI: %s\n", $input, $error->getMessage());
    }
}
?>

运行前确认 CLI 使用的是 PHP 8.5：php -v。这个检查只验证读取路径，不代表已经完成参数授权、业务类型校验或 URL 安全策略。

相关问题

getQuery() 会直接返回数组吗？

不会。它返回规范化查询字符串或 null；需要数组时再使用 parse_str()，并对字段做白名单和类型校验。

什么时候应该用 getRawQuery()？

签名、审计或需要保留原始百分号编码时使用。只做常规业务筛选时通常使用规范化后的 getQuery()。

Uri\Rfc3986\Uri 和 Uri\WhatWg\Url 能随意互换吗？

不能。两者遵循的标准不同，应按输入协议和兼容要求选择；方法名相近不等于解析结果完全相同。

实际项目可以把流程固定成“选规范、构造对象、判断 null、读取查询、再做业务校验”五步。这样既不会误把 UriUrl 当成真实类名，也不会把 URI 解析和参数信任混在一起。