Kit UrlParser
Version 2.2.0
UrlParser是 PHP 函式庫，提供符合 RFC 3986 的 URL 解析器和 PSR-7 相容的 URI 元件。這個函式庫的目的是提供一個準確實作 RFC 規範的解析器，這與內建函數parse_url()不同，後者在一些微妙的方面與規範有所不同。
這個庫有兩個主要目的。第一個從解析的 URL 中提供資訊。為了實現這一目標，該程式庫實現了 PSR-7 中的標準 URI 處理接口，並且還提供了其他方法，使從 URL 檢索常用資訊變得更加容易。第二個目的是也允許使用 PSR-7 標準的介面修改所述 URL，此外還有一些使某些任務更加簡單的額外方法。
雖然該函式庫主要用於解析 URL，但解析只是基於通用 URI 語法。因此，可以使用該程式庫根據通用語法驗證和解析任何其他類型的 URI。該程式庫不會對 URL 執行任何特定於方案的驗證。
除了預設的 RFC 3986 相容模式之外，該程式庫還提供允許解析 URL 不同元件中包含 UTF-8 字元的 URL 的選項，同時將它們轉換為適當的百分比編碼和 IDN ascii 格式。
API 文件位於：http://kit.riimu.net/api/urlparser/
^1.0 )intl （僅需 IDN 支援） 安裝此程式庫的最簡單方法是使用 Composer 來處理依賴項。若要透過 Composer 安裝此程式庫，只需執行以下兩個步驟：
透過在專案根目錄中執行 Composer 命令列安裝來取得composer.phar 。
執行安裝腳本後，專案根目錄中應該有composer.phar文件，並且可以執行以下命令：
php composer.phar require "riimu/kit-urlparser:^2.1"
透過 Composer 安裝此程式庫後，您可以透過包含 Composer 在安裝過程中產生的vendor/autoload.php檔案來載入該程式庫。
如果您已經熟悉如何使用 Composer，您也可以透過將以下composer.json檔案新增至您的專案並執行composer install命令來將該程式庫新增為依賴項：
{
"require" : {
"riimu/kit-urlparser" : " ^2.1 "
}
}如果您不想使用 Composer 載入庫，您也可以透過下載最新版本並將src資料夾解壓縮到您的專案來手動下載庫。然後，您可以包含提供的src/autoload.php檔案來載入庫類別。
請注意，使用 Composer 也會自動下載其他所需的 PHP 函式庫。如果您手動安裝此庫，您還需要使其他必要的庫可用。
使用這個庫相對簡單。該函式庫提供了一個 URL 解析類別UriParser和一個表示 URL 的不可變值物件類別Uri 。要解析 URL，您只需將 URL 作為字串提供給UriParser中的parse()方法，該方法傳回從解析的 URL 產生的Uri實例。
例如：
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ uri = $ parser -> parse ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com'或者，您可以完全跳過使用UriParser並簡單地將 URL 作為建構子參數提供給Uri ：
<?php
require ' vendor/autoload.php ' ;
$ uri = new Riimu Kit UrlParser Uri ( ' http://www.example.com ' );
echo $ uri -> getHost (); // Outputs 'www.example.com'使用parse()方法和建構子之間的主要區別在於，如果提供的 URL 不是有效的 url，則parse()方法將傳回null ，而建構子將拋出InvalidArgumentException 。
要從 URL 檢索不同類型的信息， Uri類別提供了各種不同的方法來幫助您。這是一個簡單的範例，概述了不同的可用方法：
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ uri = $ parser -> parse ( ' http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form ' );
echo $ uri -> getScheme () . PHP_EOL ; // outputs: http
echo $ uri -> getUsername () . PHP_EOL ; // outputs: jane
echo $ uri -> getPassword () . PHP_EOL ; // outputs: pass123
echo $ uri -> getHost () . PHP_EOL ; // outputs: www.example.com
echo $ uri -> getTopLevelDomain () . PHP_EOL ; // outputs: com
echo $ uri -> getPort () . PHP_EOL ; // outputs: 8080
echo $ uri -> getStandardPort () . PHP_EOL ; // outputs: 80
echo $ uri -> getPath () . PHP_EOL ; // outputs: /site/index.php
echo $ uri -> getPathExtension () . PHP_EOL ; // outputs: php
echo $ uri -> getQuery () . PHP_EOL ; // outputs: action=login&prev=index
echo $ uri -> getFragment () . PHP_EOL ; // outputs: form
print_r ( $ uri -> getPathSegments ()); // [0 => 'site', 1 => 'index.php']
print_r ( $ uri -> getQueryParameters ()); // ['action' => 'login', 'prev' => 'index'] Uri元件還提供了各種修改 URL 的方法，讓您可以從單獨的元件建構新的 URL 或修改現有的 URL。請注意， Uri元件是一個不可變的值對象，這表示每個修改方法都會傳回一個新的Uri實例，而不是修改現有的 Uri 實例。以下是一個從其元件建構 URL 的簡單範例：
<?php
require ' vendor/autoload.php ' ;
$ uri = ( new Riimu Kit UrlParser Uri ())
-> withScheme ( ' http ' )
-> withUserInfo ( ' jane ' , ' pass123 ' )
-> withHost ( ' www.example.com ' )
-> withPort ( 8080 )
-> withPath ( ' /site/index.php ' )
-> withQueryParameters ([ ' action ' => ' login ' , ' prev ' => ' index ' ])
-> withFragment ( ' form ' );
// Outputs: http://jane:[email protected]:8080/site/index.php?action=login&prev=index#form
echo $ uri ;從前面的範例可以看出， Uri元件也提供了__toString()方法，該方法以字串形式提供 URL。
以下是Uri組件提供的用於從 URL 檢索資訊的方法清單：
getScheme()傳回 URL 中的方案，如果 URL 沒有方案，則傳回空字串。
getAuthority()從 URL 傳回由使用者名稱、密碼、主機名稱和連接埠組成的元件，格式為user-info@hostname:port
getUserInfo()從 URL 傳回包含以冒號分隔的使用者名稱和密碼的元件。
getUsername()傳回從 URL解碼的使用者名，如果 URL 中不存在使用者名，則傳回空字串。
getPassword()傳回 URL 中解碼後的密碼，如果 URL 中不存在密碼，則傳回空字串。
getHost()傳回 URL 中的主機名，如果 URL 沒有主機，則傳回空字串。
如果主機是 IP 位址，則getIpAddress()傳回主機的 IP 位址。否則此方法將傳回null 。如果提供了 IPv6 位址，則傳回的位址不帶大括號。
getTopLevelDomain()傳回主機的頂級域。如果沒有主機或主機是IP位址，則傳回空字串。
getPort()傳回 URL 中的端口，如果 url 中不存在端口，則傳回null 。如果連接埠是目前方案的標準連接埠（例如，http 為 80），則此方法也會傳回null 。
getStandardPort()傳回目前方案的標準連接埠。如果沒有方案或方案的標準連接埠未知，則將傳回null 。
getPath()傳回 URL 的路徑，如果 URL 沒有路徑，則傳回空字串。
getPathSegments()傳回已解碼路徑段的陣列（即由每個正斜線分割的路徑）。空路徑段將被丟棄，並且不包含在傳回的陣列中。
getPathExtension()從路徑傳回檔案副檔名；如果 URL 沒有路徑，則傳回空字串。
getQuery()傳回 URL 中的查詢字串；如果 URL 沒有查詢字串，則傳回空字串。
getQueryParameters()使用parse_str()函數從 URL 解析查詢字串並傳回解析值的陣列。
getFragment()傳回 URL 中的片段，如果 URL 沒有片段，則傳回空字串。
__toString()以字串形式傳回 URL。
Uri元件提供了各種可用於修改 URL 和建構新 URL 的方法。請注意，由於Uri類別是一個不可變值對象，因此每個方法都會傳回一個新的Uri實例，而不是修改現有實例。
withScheme($scheme)傳回具有給定方案的新實例。空方案可用於從 URL 中刪除方案。請注意，任何提供的方案都會標準化為小寫。
withUserInfo($user, $password = null)傳回具有給定使用者名稱和密碼的新實例。請注意，除非提供使用者名，否則密碼將被忽略。空白用戶名可用於從 URL 中刪除使用者名稱和密碼。任何無法單獨插入 URL 的字元都將進行百分比編碼。
withHost($host)傳回具有給定主機的新實例。空主機可用於從 URL 中刪除主機。請注意，此方法不接受國際域名。請注意，此方法還將主機標準化為小寫。
withPort($port)傳回具有給定連接埠的新執行個體。 null可用於從 URL 中刪除連接埠。
withPath($path)傳回具有給定路徑的新實例。空路徑可用於從 URL 中刪除路徑。請注意，任何不是有效路徑字元的字元都會在 URL 中進行百分比編碼。但是，現有的百分比編碼字元不會進行雙重編碼。
withPathSegments(array $segments)傳回一個新實例，其中路徑由路徑段陣列建構而成。段落中的所有無效路徑字元都將進行百分比編碼，包括正斜線和現有的百分比編碼字元。
withQuery($query)傳回具有給定查詢字串的新實例。空查詢字串可用於從 URL 中刪除路徑。請注意，任何不是有效查詢字串字元的字元都將在 URL 中進行百分比編碼。但是，現有的百分比編碼字元不會進行雙重編碼。
withQueryParameters(array $parameters)傳回一個新實例，其中包含使用http_build_query()函數根據提供的參數建構的查詢字串。參數中的所有無效查詢字串字元都將進行百分比編碼，包括與號、等號和現有的百分比編碼字元。
withFragment($fragment)傳回具有給定片段的新實例。空字串可用於從 URL 中刪除片段。請注意，任何不是有效片段字元的字元都會在 URL 中進行百分比編碼。但是，現有的百分比編碼字元不會進行雙重編碼。
預設情況下，該程式庫提供符合 RFC 3986 的解析器。 RFC 規範不允許在網域名稱或 URL 的任何其他部分中使用 UTF-8 字元。 URL 中這些內容的正確表示是使用網域名稱的 IDN 標準，並在其他部分對 UTF-8 字元進行百分比編碼。
但是，為了幫助您處理 UTF-8 編碼字符， Uri組件中的許多方法將自動對無法自行插入 URL 中的任何字符（包括 UTF-8 字符）進行百分比編碼。然而，由於涉及的複雜性， withHost()方法不允許使用 UTF-8 編碼的字元。
預設情況下，解析器也不解析任何包含 UTF-8 編碼字元的 URL，因為這違反了 RFC 規範。然而，解析器確實提供了兩種額外的解析模式，只要有可能就允許這些字元。
如果您希望解析 URL 中的使用者資訊（即使用者名稱或密碼）、路徑、查詢或片段元件中可能包含 UTF-8 字元的 URL，則可以簡單地使用 UTF-8 解析模式。例如：
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ parser -> setMode ( Riimu Kit UrlParser UriParser:: MODE_UTF8 );
$ uri = $ parser -> parse ( ' http://www.example.com/föö/bär.html ' );
echo $ uri -> getPath (); // Outputs: /f%C3%B6%C3%B6/b%C3%A4r.html然而，網域名稱中的 UTF-8 字元是一個稍微複雜的問題。不過，解析器確實為使用 IDNA 模式解析這些網域提供了基本支援。例如：
<?php
require ' vendor/autoload.php ' ;
$ parser = new Riimu Kit UrlParser UriParser ();
$ parser -> setMode ( Riimu Kit UrlParser UriParser:: MODE_IDNA );
$ uri = $ parser -> parse ( ' http://www.fööbär.com ' );
echo $ uri -> getHost (); // Outputs: www.xn--fbr-rla2ga.com請注意，使用此解析模式需要啟用 PHP 擴充intl 。也可以使用第二個建構函式參數向Uri元件的建構函式提供適當的解析模式。
雖然支援解析這些 UTF-8 字符，但該庫不提供任何反向操作方法，因為該庫的目的是處理符合 RFC 3986 的 URI。
由於 RFC 3986 規範將一些 URL 定義為等效的，儘管存在一些細微的差異，因此該程式庫對提供的值進行了一些最小的標準化。例如，在解析使用者提供的 URL 時，您可能會遇到這些情況。您可能遇到的最值得注意的標準化如下：
scheme和host組件被認為不區分大小寫。因此，這些組件將始終標準化為小寫。getAuthority()和__toString()傳回的字串中。__toString()傳回的字串中路徑開頭的正斜線數量可能會根據 URL 是否具有authority元件而改變。userinfo元件中解析和產生的 URI 中的編碼字元百分比可能會有所不同，因為UriParser使用 PSR-7 規範，該規範不提供提供編碼使用者名稱或密碼的方法。 該庫版權所有 (c) 2013-2022 Riikka Kalliomaki。
有關許可證和複製信息，請參閱許可證。
