~~~php <?php namespace Psr\Http\Message; /** * URI 數據對象。 * * 此接口按照 RFC 3986 來構建 HTTP URI，提供了一些通用的操作，你可以自由的對此接口 * 進行擴展。你可以使用此 URI 接口來做 HTTP 相關的操作，也可以使用此接口做任何 URI * 相關的操作。 * * 此接口的實例化對象被視為無法修改的，所有能修改狀態的方法，都 **必須** 有一套機制，在內部保 * 持好原有的內容，然后把修改狀態后的，新的實例返回。 * * 通常，HOST 信息也將出現在請求消息中。對于服務器端的請求，通常可以在服務器參數中發現此信息。 * * @see [URI 通用標準規范](http://tools.ietf.org/html/rfc3986) */ interface UriInterface { /** * 從 URI 中取出 scheme。 * * 如果不存在 Scheme，此方法 **必須** 返回空字符串。 * * 根據 RFC 3986 規范 3.1 章節，返回的數據 **必須** 是小寫字母。 * * 最后部分的「:」字串不屬于 Scheme，**不得** 作為返回數據的一部分。 * * @see https://tools.ietf.org/html/rfc3986#section-3.1 * @return string URI Ccheme 的值。 */ public function getScheme(); /** * 返回 URI 認證信息。 * * 如果沒有 URI 認證信息的話，**必須** 返回一個空字符串。 * * URI 的認證信息語法是： * * <pre> * [user-info@]host[:port] * </pre> * * 如果端口部分沒有設置，或者端口不是標準端口，**不應該** 包含在返回值內。 * * @see https://tools.ietf.org/html/rfc3986#section-3.2 * @return string URI 認證信息，格式為：「[user-info@]host[:port]」。 */ public function getAuthority(); /** * 從 URI 中獲取用戶信息。 * * 如果不存在用戶信息，此方法 **必須** 返回一個空字符串。 * * 如果 URI 中存在用戶，則返回該值；此外，如果密碼也存在，它將附加到用戶值，用冒號（「:」）分隔。 * * 用戶信息后面跟著的 "@" 字符，不是用戶信息里面的一部分，**不得** 在返回值里出現。 * * @return string URI 的用戶信息，格式："username[:password]" */ public function getUserInfo(); /** * 從 URI 中獲取 HOST 信息。 * * 如果 URI 中沒有此值，**必須** 返回空字符串。 * * 根據 RFC 3986 規范 3.2.2 章節，返回的數據 **必須** 是小寫字母。 * * @see http://tools.ietf.org/html/rfc3986#section-3.2.2 * @return string URI 中的 HOST 信息。 */ public function getHost(); /** * 從 URI 中獲取端口信息。 * * 如果端口信息是與當前 Scheme 的標準端口不匹配的話，就使用整數值的格式返回，如果是一 * 樣的話，**應該** 返回 `null` 值。 * * 如果不存在端口和 Scheme 信息，**必須** 返回 `null` 值。 * * 如果不存在端口數據，但是存在 Scheme 的話，**可能** 返回 Scheme 對應的 * 標準端口，但是 **應該** 返回 `null`。 * * @return null|int URI 中的端口信息。 */ public function getPort(); /** * 從 URI 中獲取路徑信息。 * * 路徑可以是空的，或者是絕對的（以斜線「/」開頭），或者相對路徑（不以斜線開頭）。 * 實現 **必須** 支持所有三種語法。 * * 根據 RFC 7230 第 2.7.3 節，通常空路徑「」和絕對路徑「/」被認為是相同的。 * 但是這個方法 **不得** 自動進行這種規范化，因為在具有修剪的基本路徑的上下文中， * 例如前端控制器中，這種差異將變得顯著。用戶的任務就是可以將「」和「/」都處理好。 * * 返回的值 **必須** 是百分號編碼，但 **不得** 對任何字符進行雙重編碼。 * 要確定要編碼的字符，請參閱 RFC 3986 第 2 節和第 3.3 節。 * * 例如，如果值包含斜線（「/」）而不是路徑段之間的分隔符，則該值必須以編碼形式（例如「%2F」） * 傳遞給實例。 * * @see https://tools.ietf.org/html/rfc3986#section-2 * @see https://tools.ietf.org/html/rfc3986#section-3.3 * @return string URI 路徑信息。 */ public function getPath(); /** * 獲取 URI 中的查詢字符串。 * * 如果不存在查詢字符串，則此方法必須返回空字符串。 * * 前導的「?」字符不是查詢字符串的一部分，**不得** 添加在返回值中。 * * 返回的值 **必須** 是百分號編碼，但 **不得** 對任何字符進行雙重編碼。 * 要確定要編碼的字符，請參閱 RFC 3986 第 2 節和第 3.4 節。 * * 例如，如果查詢字符串的鍵值對中的值包含不做為值之間分隔符的（「&」），則該值必須 * 以編碼形式傳遞（例如「%26」）到實例。 * * @see https://tools.ietf.org/html/rfc3986#section-2 * @see https://tools.ietf.org/html/rfc3986#section-3.4 * @return string URI 中的查詢字符串 */ public function getQuery(); /** * 獲取 URI 中的片段（Fragment）信息。 * * 如果沒有片段信息，此方法 **必須** 返回空字符串。 * * 前導的「#」字符不是片段的一部分，**不得** 添加在返回值中。 * * 返回的值 **必須** 是百分號編碼，但 **不得** 對任何字符進行雙重編碼。 * 要確定要編碼的字符，請參閱 RFC 3986 第 2 節和第 3.5 節。 * * @see https://tools.ietf.org/html/rfc3986#section-2 * @see https://tools.ietf.org/html/rfc3986#section-3.5 * @return string URI 中的片段信息。 */ public function getFragment(); /** * 返回具有指定 Scheme 的實例。 * * 此方法 **必須** 保留當前實例的狀態，并返回包含指定 Scheme 的實例。 * * 實現 **必須** 支持大小寫不敏感的「http」和「https」的 Scheme，并且在 * 需要的時候 **可能** 支持其他的 Scheme。 * * 空的 Scheme 相當于刪除 Scheme。 * * @param string $scheme 給新實例使用的 Scheme。 * @return self 具有指定 Scheme 的新實例。 * @throws \InvalidArgumentException 使用無效的 Scheme 時拋出。 * @throws \InvalidArgumentException 使用不支持的 Scheme 時拋出。 */ public function withScheme($scheme); /** * 返回具有指定用戶信息的實例。 * * 此方法 **必須** 保留當前實例的狀態，并返回包含指定用戶信息的實例。 * * 密碼是可選的，但用戶信息 **必須** 包括用戶；用戶信息的空字符串相當于刪除用戶信息。 * * @param string $user 用于認證的用戶名。 * @param null|string $password 密碼。 * @return self 具有指定用戶信息的新實例。 */ public function withUserInfo($user, $password = null); /** * 返回具有指定 HOST 信息的實例。 * * 此方法 **必須** 保留當前實例的狀態，并返回包含指定 HOST 信息的實例。 * * 空的 HOST 信息等同于刪除 HOST 信息。 * * @param string $host 用于新實例的 HOST 信息。 * @return self 具有指定 HOST 信息的實例。 * @throws \InvalidArgumentException 使用無效的 HOST 信息時拋出。 */ public function withHost($host); /** * 返回具有指定端口的實例。 * * 此方法 **必須** 保留當前實例的狀態，并返回包含指定端口的實例。 * * 實現 **必須** 為已建立的 TCP 和 UDP 端口范圍之外的端口引發異常。 * * 為端口提供的空值等同于刪除端口信息。 * * @param null|int $port 用于新實例的端口；`null` 值將刪除端口信息。 * @return self 具有指定端口的實例。 * @throws \InvalidArgumentException 使用無效端口時拋出異常。 */ public function withPort($port); /** * 返回具有指定路徑的實例。 * * 此方法 **必須** 保留當前實例的狀態，并返回包含指定路徑的實例。 * * 路徑可以是空的、絕對的（以斜線開頭）或者相對路徑（不以斜線開頭），實現必須支持這三種語法。 * * 如果 HTTP 路徑旨在與 HOST 相對而不是路徑相對，，那么它必須以斜線開頭。 * 假設 HTTP 路徑不以斜線開頭，對應該程序或開發人員來說，相對于一些已知的路徑。 * * 用戶可以提供編碼和解碼的路徑字符，要確保實現了 `getPath()` 中描述的正確編碼。 * * @param string $path 用于新實例的路徑。 * @return self 具有指定路徑的實例。 * @throws \InvalidArgumentException 使用無效的路徑時拋出。 */ public function withPath($path); /** * 返回具有指定查詢字符串的實例。 * * 此方法 **必須** 保留當前實例的狀態，并返回包含查詢字符串的實例。 * * 用戶可以提供編碼和解碼的查詢字符串，要確保實現了 `getQuery()` 中描述的正確編碼。 * * 空查詢字符串值等同于刪除查詢字符串。 * * @param string $query 用于新實例的查詢字符串。 * @return self 具有指定查詢字符串的實例。 * @throws \InvalidArgumentException 使用無效的查詢字符串時拋出。 */ public function withQuery($query); /** * 返回具有指定 URI 片段（Fragment）的實例。 * * 此方法 **必須** 保留當前實例的狀態，并返回包含片段的實例。 * * 用戶可以提供編碼和解碼的片段，要確保實現了 `getFragment()` 中描述的正確編碼。 * * 空片段值等同于刪除片段。 * * @param string $fragment 用于新實例的片段。 * @return self 具有指定 URI 片段的實例。 */ public function withFragment($fragment); /** * 返回字符串表示形式的 URI。 * * 根據 RFC 3986 第 4.1 節，結果字符串是完整的 URI 還是相對引用，取決于 URI 有哪些組件。 * 該方法使用適當的分隔符連接 URI 的各個組件： * * - 如果存在 Scheme 則 **必須** 以「:」為后綴。 * - 如果存在認證信息，則必須以「//」作為前綴。 * - 路徑可以在沒有分隔符的情況下連接。但是有兩種情況需要調整路徑以使 URI 引用有效，因為 PHP * 不允許在 `__toString()` 中引發異常： * - 如果路徑是相對的并且有認證信息，則路徑 **必須** 以「/」為前綴。 * - 如果路徑以多個「/」開頭并且沒有認證信息，則起始斜線 **必須** 為一個。 * - 如果存在查詢字符串，則 **必須** 以「?」作為前綴。 * - 如果存在片段（Fragment），則 **必須** 以「#」作為前綴。 * * @see http://tools.ietf.org/html/rfc3986#section-4.1 * @return string */ public function __toString(); } ~~~