PHP8.5 的新 URI 擴展

URL 是我們每(mei)天依賴的 Web 的基(ji)礎(chu)構建塊(kuai)。

它們的熟悉度讓它們看起來簡單(dan)得(de)有些欺騙性：看似清晰(xi)劃分的組件，如 scheme、hostname、path 等，讓人(ren)覺得(de)從 URL 中提取信息(xi)是件小(xiao)事。但(dan)實(shi)際上，多年來已經構建了數(shu)千個自定義解(jie)(jie)析(xi)器，每個都有自己對細節(jie)的理(li)解(jie)(jie)。

對(dui)我們 Web 開(kai)發者來說，有兩(liang)個(ge)主要標(biao)準(zhun)(zhun)規定了 URL 應該如何工(gong)作。RFC 3986，這(zhe)是(shi) 2005 年(nian)的原始 URI 標(biao)準(zhun)(zhun)；以及 WHATWG URL Living Standard，Web 瀏覽器遵循的標(biao)準(zhun)(zhun)。因為事(shi)情并不像乍(zha)看起來那么簡單，這(zhe)兩(liang)個(ge)常用標(biao)準(zhun)(zhun)彼此不兼(jian)容(rong)！混合使用不同的標(biao)準(zhun)(zhun)及其解析器，特(te)別是(shi)當它們沒有完全(quan)遵循標(biao)準(zhun)(zhun)時，通常會導致安全(quan)問題。

為什么需要改變

盡管正確解析 URL 很重要，但 PHP 長期以來在標準庫中并沒有包含任何符合標準的解析器。雖然有 parse_url() 函數，它從 PHP 4 就存在了，但它不遵循任何標準，并且在文檔中明確說明不要用于不受信任或格式錯誤的 URL。盡管如此，由于缺乏更好的替代方案，而且它對開發者日常工作中遇到的大多數格式良好的輸入似乎都能正常工作，所以它被廣泛使用。這可能會誤導開發者認為 parse_url() 的(de)安全問題(ti)(ti)純粹是理論問題(ti)(ti)，而不是遲早會導致問題(ti)(ti)的(de)東西。

舉個例子，輸入 URL example.com/example/:8080/foo 根據 RFC 3986 是一個有效的 URL，僅由相對路徑組成。如果不針對基礎 URL 解析，根據 WHATWG URL 標準它是無效的。然而，根據 parse_url() 的解析，它是主機為 example.com、端口為 8080、路徑為 /example/:8080/foo 的 URL，因此在兩個結果組件(jian)中都包含(han)了 8080：

<?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

這(zhe)在 PHP 8.5 中發生了變化。從現在開始，PHP 將在新的(de) "URI" 擴展(zhan)中包(bao)含符合 RFC 3986 和 WHATWG URL 標(biao)準(zhun)的(de)解析器，作為標(biao)準(zhun)庫(ku)中始終可用的(de)一部分(fen)。這(zhe)不僅(jin)能夠根(gen)據(ju)各自(zi)的(de)標(biao)準(zhun)輕松、正確、安全地解析 URL，而且 URI 擴展(zhan)還(huan)包(bao)含修改 URL 各個(ge)組件(jian)的(de)功(gong)能。

<?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;
// 輸出: //thephp.foundation/sponsor/
echo $url->toRawString(), PHP_EOL;
// 輸出: HTTPS://thephp.foundation/sp%6Fnsor/

精心構建以持久使用

在這篇文(wen)章中，我們不僅想展(zhan)示功(gong)能(neng)，還想告訴你這個項目是(shi)(shi)如何發(fa)展(zhan)的，以及在 PHP 中如何完成工(gong)作以保持語言現(xian)代化(hua)，成為 Web 開發(fa)的絕(jue)佳選擇。新 PHP 功(gong)能(neng)背(bei)后的工(gong)作往(wang)往(wang)比表面看到的要(yao)多。我們希望提供一(yi)些見解，說明為什么我們更喜歡(huan)把(ba)事情做對而(er)不是(shi)(shi)做快(kuai)。

來自(zi) PHP 基(ji)金會(hui)開(kai)發團隊的(de)(de) Máté Kocsis 最初在(zai) 2024 年(nian) 6 月開(kai)始討論(lun)他(ta)關(guan)于(yu)新 URL 解析 API 的(de)(de) RFC。鑒(jian)于(yu) PHP 強大的(de)(de)向后兼容性(xing)承諾，新 API 需要在(zai)第一(yi)次(ci)(ci)嘗試時就把(ba)事情做對，以(yi)便在(zai)未來十年(nian)內為(wei)(wei) PHP 社區提(ti)(ti)供(gong)良好(hao)服務，而(er)不會(hui)引入破壞性(xing)變(bian)化。因此(ci)，在(zai)將(jiang)近(jin)一(yi)年(nian)的(de)(de)時間里，PHP Internals 郵(you)(you)件列表上(shang)發送了(le) 150 多封電子郵(you)(you)件。此(ci)外，還(huan)(huan)在(zai)各(ge)種(zhong)聊天(tian)室進行了(le)多次(ci)(ci)非列表討論(lun)。在(zai)整個過程中(zhong)，來自(zi) PHP 社區的(de)(de)各(ge)種(zhong)專家不斷完善 RFC。他(ta)們(men)(men)討論(lun)了(le)即(ji)使是看似微不足道的(de)(de)細節，不僅要提(ti)(ti)供(gong)符(fu)合標準的(de)(de)實(shi)現，還(huan)(huan)要提(ti)(ti)供(gong)一(yi)個干凈、健壯的(de)(de) API，引導開(kai)發者為(wei)(wei)他(ta)們(men)(men)的(de)(de)用例(li)找到正(zheng)確(que)的(de)(de)解決方(fang)案(an)。我(wo)們(men)(men)還(huan)(huan)提(ti)(ti)前(qian)規劃，確(que)保新的(de)(de) URI 擴展及其專用的(de)(de) Uri 命名空間為(wei)(wei)在(zai)未來版本(ben)的(de)(de) PHP 中(zhong)添加額外的(de)(de) URI/URL 相關(guan)功能(neng)提(ti)(ti)供(gong)了(le)清晰的(de)(de)路徑。

RFC 最終在 2025 年 5 月進行投票，并(bing)以 30:1 的(de)(de)投票結果獲得通過。但工作并(bing)沒有(you)就此停止：提(ti)議的(de)(de) API 還必(bi)須實(shi)現和審查。Máté 沒有(you)構建一個 PHP 特定的(de)(de)解決方案，而(er)是選擇站在巨(ju)人(ren)的(de)(de)肩膀(bang)上，選擇了兩(liang)個庫(ku)來完(wan)成繁重的(de)(de)工作。uriparser 庫(ku)提(ti)供 RFC 3986 解析(xi)器，而(er) Lexbor 庫(ku)（已被 PHP 8.4 的(de)(de)新(xin) DOM API 使(shi)用）提(ti)供 WHATWG 解析(xi)器。

開源協作

作為集成的一部分，Máté 和 PHP 基金會與上游維護者合作，在各自的庫中包含缺失的功能。例如，這兩個庫都不包含廉價復制內部數據結構的功能，而這對于支持在嘗試使用所謂的 with-er 方法（例如 ->withPort(8080)）修改各(ge)個組(zu)件(jian)時克隆(long)表(biao)示(shi)已解(jie)析 URL 的(de)(de)只讀(du) PHP 對象是必需的(de)(de)。uriparser 庫也不包含任何用(yong)于(yu)修改已解(jie)析 URL 組(zu)件(jian)的(de)(de)函數。所有這(zhe)些功(gong)能現在(zai)都可以在(zai)上游庫中(zhong)供所有人使(shi)用(yong)和受益。

Máté 的(de)(de)(de) PHP 實現的(de)(de)(de)審(shen)(shen)查(cha)(cha)和(he)測(ce)試由 PHP 社區(qu)貢獻者(zhe) Niels Dossche 和(he) Ignace Nyamagana Butera 進(jin)行(xing)。這(zhe)包括審(shen)(shen)查(cha)(cha)和(he)測(ce)試已添加到兩個上游(you)庫的(de)(de)(de)新功(gong)能。Tideways，PHP 基金會的(de)(de)(de)創始成員(yuan)和(he)白銀贊(zan)助(zhu)商，也(ye)贊(zan)助(zhu)了工程時間；他(ta)們(men)的(de)(de)(de)貢獻以 Tim Düsterhus 的(de)(de)(de)形式出(chu)現。在審(shen)(shen)查(cha)(cha)和(he)測(ce)試期間，這(zhe)些(xie)審(shen)(shen)查(cha)(cha)者(zhe)在上游(you)庫中發現了幾(ji)個預先存在的(de)(de)(de) bug。他(ta)們(men)向(xiang)上游(you)維護者(zhe) Sebastian Pipping（uriparser）和(he) Alexander Borisov（Lexbor）提交了修復，他(ta)們(men)迅速(su)審(shen)(shen)查(cha)(cha)并應用了這(zhe)些(xie)修復。

立即測試

這(zhe)項工作得到了回(hui)報，PHP 的新 URI 擴展不僅(jin)有一個而是兩個功(gong)能豐富且符合標準的 URI 實現，現在可(ke)以在 PHP 8.5 RC 1 中(zhong)完全測試。