PHP8.5 的新 URI 扩展

URL 是我们每天依赖的 Web 的基础构建块。

它们的熟悉度让它们看起来简单得有些欺骗性：看似清晰划分的组件，如 scheme、hostname、path 等，让人觉得从 URL 中提取信息是件小事。但实际上，多年来已经构建了数千个自定义解析器，每个都有自己对细节的理解。

对我们 Web 开发者来说，有两个主要标准规定了 URL 应该如何工作。RFC 3986，这是 2005 年的原始 URI 标准；以及 WHATWG URL Living Standard，Web 浏览器遵循的标准。因为事情并不像乍看起来那么简单，这两个常用标准彼此不兼容！混合使用不同的标准及其解析器，特别是当它们没有完全遵循标准时，通常会导致安全问题。

原文链接 PHP8.5 的新 URI 扩展

为什么需要改变

尽管正确解析 URL 很重要，但 PHP 长期以来在标准库中并没有包含任何符合标准的解析器。虽然有 parse_url() 函数，它从 PHP 4 就存在了，但它不遵循任何标准，并且在文档中明确说明不要用于不受信任或格式错误的 URL。尽管如此，由于缺乏更好的替代方案，而且它对开发者日常工作中遇到的大多数格式良好的输入似乎都能正常工作，所以它被广泛使用。这可能会误导开发者认为 parse_url() 的安全问题纯粹是理论问题，而不是迟早会导致问题的东西。

举个例子，输入 URL example.com/example/:8080/foo 根据 RFC 3986 是一个有效的 URL，仅由相对路径组成。如果不针对基础 URL 解析，根据 WHATWG URL 标准它是无效的。然而，根据 parse_url() 的解析，它是主机为 example.com、端口为 8080、路径为 /example/:8080/foo 的 URL，因此在两个结果组件中都包含了 8080：

php 复制代码

<?php

var_dump(parse_url('example.com/example/:8080/foo'));

/*
array(3) {
  ["host"]=> string(11) "example.com"
  ["port"]=> int(8080)
  ["path"]=> string(18) "/example/:8080/foo"
}
*/

引入新 API

这在 PHP 8.5 中发生了变化。从现在开始，PHP 将在新的 "URI" 扩展中包含符合 RFC 3986 和 WHATWG URL 标准的解析器，作为标准库中始终可用的一部分。这不仅能够根据各自的标准轻松、正确、安全地解析 URL，而且 URI 扩展还包含修改 URL 各个组件的功能。

php 复制代码

<?php

use Uri\Rfc3986\Uri;

$url = new Uri('HTTPS://thephp.foundation:443/sp%6Fnsor/');

$defaultPortForScheme = match ($url->getScheme()) {
    'http' => 80,
    'https' => 443,
    'ssh' => 22,
    default => null,
};

// 从 URL 中删除默认端口
if ($url->getPort() === $defaultPortForScheme) {
    $url = $url->withPort(null);
}

// Getter 默认会规范化 URL。`Raw` 
// 变体会原样返回输入。

echo $url->toString(), PHP_EOL;
// 输出: https://thephp.foundation/sponsor/
echo $url->toRawString(), PHP_EOL;
// 输出: HTTPS://thephp.foundation/sp%6Fnsor/

精心构建以持久使用

在这篇文章中，我们不仅想展示功能，还想告诉你这个项目是如何发展的，以及在 PHP 中如何完成工作以保持语言现代化，成为 Web 开发的绝佳选择。新 PHP 功能背后的工作往往比表面看到的要多。我们希望提供一些见解，说明为什么我们更喜欢把事情做对而不是做快。

来自 PHP 基金会开发团队的 Máté Kocsis 最初在 2024 年 6 月开始讨论他关于新 URL 解析 API 的 RFC。鉴于 PHP 强大的向后兼容性承诺，新 API 需要在第一次尝试时就把事情做对，以便在未来十年内为 PHP 社区提供良好服务，而不会引入破坏性变化。因此，在将近一年的时间里，PHP Internals 邮件列表上发送了 150 多封电子邮件。此外，还在各种聊天室进行了多次非列表讨论。在整个过程中，来自 PHP 社区的各种专家不断完善 RFC。他们讨论了即使是看似微不足道的细节，不仅要提供符合标准的实现，还要提供一个干净、健壮的 API，引导开发者为他们的用例找到正确的解决方案。我们还提前规划，确保新的 URI 扩展及其专用的 Uri 命名空间为在未来版本的 PHP 中添加额外的 URI/URL 相关功能提供了清晰的路径。

RFC 最终在 2025 年 5 月进行投票，并以 30:1 的投票结果获得通过。但工作并没有就此停止：提议的 API 还必须实现和审查。Máté 没有构建一个 PHP 特定的解决方案，而是选择站在巨人的肩膀上，选择了两个库来完成繁重的工作。uriparser 库提供 RFC 3986 解析器，而 Lexbor 库（已被 PHP 8.4 的新 DOM API 使用）提供 WHATWG 解析器。

开源协作

作为集成的一部分，Máté 和 PHP 基金会与上游维护者合作，在各自的库中包含缺失的功能。例如，这两个库都不包含廉价复制内部数据结构的功能，而这对于支持在尝试使用所谓的 with-er 方法（例如 ->withPort(8080)）修改各个组件时克隆表示已解析 URL 的只读 PHP 对象是必需的。uriparser 库也不包含任何用于修改已解析 URL 组件的函数。所有这些功能现在都可以在上游库中供所有人使用和受益。

Máté 的 PHP 实现的审查和测试由 PHP 社区贡献者 Niels Dossche 和 Ignace Nyamagana Butera 进行。这包括审查和测试已添加到两个上游库的新功能。Tideways，PHP 基金会的创始成员和白银赞助商，也赞助了工程时间；他们的贡献以 Tim Düsterhus 的形式出现。在审查和测试期间，这些审查者在上游库中发现了几个预先存在的 bug。他们向上游维护者 Sebastian Pipping（uriparser）和 Alexander Borisov（Lexbor）提交了修复，他们迅速审查并应用了这些修复。

立即测试

这项工作得到了回报，PHP 的新 URI 扩展不仅有一个而是两个功能丰富且符合标准的 URI 实现，现在可以在 PHP 8.5 RC 1 中完全测试。

来自 PHP 基金博客