PHP 8.5 Uri 类如何规范化包含端口的地址

处理内网 API 或回调地址时，端口往往不是可有可无的字符串：https://api.example.test:8443/v1/orders 里的 8443 可能决定请求究竟落到哪一层网关。PHP 8.5 的 URI 扩展提供了更明确的对象 API：用 Uri\\Rfc3986\\Uri 解析地址，用 getPort() 读取规范化端口，用 withPort() 生成另一个端口版本，最后交给 toString() 重组 URI。

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

要规范化包含端口的地址，先读取 getPort() 判断输入状态，再用 withPort(?int) 生成新对象，最后用 toString() 得到规范化字符串；不要直接在原字符串上按冒号切分。

PHP 8.5 的 Uri 类到底规范化了哪些信息

这次变化的重点不是把一个字符串“洗一遍”，而是把 URI 拆成有类型的组件。官方 URI 扩展同时覆盖 RFC 3986 URI 和 WHATWG URL 两套模型；当前问题使用 Uri\\Rfc3986\\Uri，更适合按 URI 语义读取 host、port、path 等部分。

端口字段尤其值得单独处理：getPort() 返回整数或 null，而 toString() 会把对象重新组合成规范化 URI。这样，业务层可以先判断端口是否存在，再决定是否套用服务配置，而不是从原字符串里猜测。

用 getPort 和 toString 读取带端口地址

先把输入限制在一个清晰的函数里。下面的例子不负责发请求，只负责解析和重组，因此可以独立放进配置加载或回调地址校验环节。代码中的注释说明了类型和异常边界，避免把解析结果误当成网络连通性证明。

 $uri->getHost(),
            // getPort() 返回 ?int：没有显式端口时不要强制转成 0。
            'port' => $uri->getPort(),
            'normalized' => $uri->toString(),
        ];
    } catch (\Uri\InvalidUriException $exception) {
        // 解析失败只代表输入不符合 URI 规则，不代表远端服务不可用。
        throw new InvalidArgumentException('URI 格式无效', 0, $exception);
    }
}

$endpoint = describeEndpoint('https://api.example.test:8443/v1/orders');
print_r($endpoint);

这里应该把 port 看成“输入中明确出现的端口”。它是 8443 时，说明后续配置可以按整数比较；它是 null 时，说明地址没有显式端口，是否采用协议默认端口应由请求客户端或业务配置决定，不能在这一层擅自补写。

用 withPort 生成新端口版本

Uri 是 final readonly class，端口变更要通过返回新对象来完成。这个细节适合配置灰度：原地址保留给默认线路，新对象交给备用网关，两个变量不会因为一次改端口而互相污染。

withPort(9443);
$withoutPort = $original->withPort(null);

echo $original->toString(), PHP_EOL;    // https://api.example.test:8443/v1/orders
echo $canary->toString(), PHP_EOL;      // https://api.example.test:9443/v1/orders
echo $withoutPort->toString(), PHP_EOL; // https://api.example.test/v1/orders

如果只是想“换端口”，优先调用 withPort()，不要拼接 ':' . $port。后者会在 IPv6 主机、用户信息、查询串或端口已存在时引入边界错误。传入 null 表示移除端口，适合把临时开发端口还原成不带显式端口的地址。

缺少端口、移除端口和非法 URI 怎么区分

三个状态不要混成一个“端口不对”。缺少端口是正常输入，getPort() 返回 null；移除端口是显式变更，结果字符串不再包含端口；非法 URI 则应在构造或修改阶段抛出异常。可以用下面这张速查表决定业务动作：

最小验证只检查结构，不测试网络：

getPort() === 8443);
assert($uri->withPort(9443)->getPort() === 9443);
assert($uri->withPort(null)->getPort() === null);
assert(str_contains($uri->toString(), ':8443/'));

相关问题：PHP 8.5 Uri 端口处理的常见疑问

getPort() 返回的是字符串还是整数？

对 Uri\\Rfc3986\\Uri 来说，方法签名是 ?int。没有显式端口时是 null，不要用空字符串或 0 代替它。

withPort() 会直接改掉原来的 Uri 吗？

不会。它返回修改后的新实例，原对象仍保留原端口。要使用新地址，必须接住返回值。

PHP 8.4 能直接使用这个类吗？

不能把它当成 8.4 的内置类使用。官方手册将该类标记为 PHP 8.5.0 起可用；旧版本应继续使用项目现有的 URI 方案，并单独安排兼容层。