[TOC] ## 安裝 ``` composer require psr/http-message ``` ### 接口 <details> <summary>Psr\Http\Message\MessageInterface </summary> ``` <?php namespace Psr\Http\Message; /** * * HTTP 消息包括客戶端向服務器發起的「請求」和服務器端返回給客戶端的「響應」。 * 此接口定義了他們通用的方法。 * * HTTP 消息是被視為無法修改的，所有能修改狀態的方法，都 **必須** 有一套 * 機制，在內部保持好原有的內容，然后把修改狀態后的信息返回。 * * @see http://www.ietf.org/rfc/rfc7230.txt * @see http://www.ietf.org/rfc/rfc7231.txt */ interface MessageInterface { /** * 獲取字符串形式的 HTTP 協議版本信息。 * * 字符串 **必須** 包含 HTTP 版本數字（如：「1.1」, 「1.0」）。 * * @return string HTTP 協議版本 */ public function getProtocolVersion(); /** * 返回指定 HTTP 版本號的消息實例。 * * 傳參的版本號只 **必須** 包含 HTTP 版本數字，如："1.1", "1.0"。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息對象，然后返回 * 一個新的帶有傳參進去的 HTTP 版本的實例 * * @param string $version HTTP 版本信息 * @return self */ public function withProtocolVersion($version); /** * 獲取所有的報頭信息 * * 返回的二維數組中，第一維數組的「鍵」代表單條報頭信息的名字，「值」是 * 以數組形式返回的，見以下實例： * * // 把「值」的數據當成字串打印出來 * foreach ($message->getHeaders() as $name => $values) { * echo $name . ': ' . implode(', ', $values); * } * * // 迭代的循環二維數組 * foreach ($message->getHeaders() as $name => $values) { * foreach ($values as $value) { * header(sprintf('%s: %s', $name, $value), false); * } * } * * 雖然報頭信息是沒有大小寫之分，但是使用 `getHeaders()` 會返回保留了原本 * 大小寫形式的內容。 * * @return string[][] 返回一個兩維數組，第一維數組的「鍵」 **必須** 為單條報頭信息的 * 名稱，對應的是由字串組成的數組，請注意，對應的「值」 **必須** 是數組形式的。 */ public function getHeaders(); /** * 檢查是否報頭信息中包含有此名稱的值，不區分大小寫 * * @param string $name 不區分大小寫的報頭信息名稱 * @return bool 找到返回 true，未找到返回 false */ public function hasHeader($name); /** * 根據給定的名稱，獲取一條報頭信息，不區分大小寫，以數組形式返回 * * 此方法以數組形式返回對應名稱的報頭信息。 * * 如果沒有對應的報頭信息，**必須** 返回一個空數組。 * * @param string $name 不區分大小寫的報頭字段名稱。 * @return string[] 返回報頭信息中，對應名稱的，由字符串組成的數組值，如果沒有對應 * 的內容，**必須** 返回空數組。 */ public function getHeader($name); /** * 根據給定的名稱，獲取一條報頭信息，不區分大小寫，以逗號分隔的形式返回 * * 此方法返回所有對應的報頭信息，并將其使用逗號分隔的方法拼接起來。 * * 注意：不是所有的報頭信息都可使用逗號分隔的方法來拼接，對于那些報頭信息，請使用 * `getHeader()` 方法來獲取。 * * 如果沒有對應的報頭信息，此方法 **必須** 返回一個空字符串。 * * @param string $name 不區分大小寫的報頭字段名稱。 * @return string 返回報頭信息中，對應名稱的，由逗號分隔組成的字串，如果沒有對應 * 的內容，**必須** 返回空字符串。 */ public function getHeaderLine($name); /** * 返回替換指定報頭信息「鍵/值」對的消息實例。 * * 雖然報頭信息是不區分大小寫的，但是此方法必須保留其傳參時的大小寫狀態，并能夠在 * 調用 `getHeaders()` 的時候被取出。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息對象，然后返回 * 一個更新后帶有傳參進去報頭信息的實例 * * @param string $name 不區分大小寫的報頭字段名稱。 * @param string|string[] $value 報頭信息或報頭信息數組。 * @return self * @throws \InvalidArgumentException 無效的報頭字段或報頭信息時拋出 */ public function withHeader($name, $value); /** * 返回一個報頭信息增量的 HTTP 消息實例。 * * 原有的報頭信息會被保留，新的值會作為增量加上，如果報頭信息不存在的話，字段會被加上。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息對象，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @param string $name 不區分大小寫的報頭字段名稱。 * @param string|string[] $value 報頭信息或報頭信息數組。 * @return self * @throws \InvalidArgumentException 報頭字段名稱非法時會被拋出。 * @throws \InvalidArgumentException 報頭頭信息的值非法的時候會被拋出。 */ public function withAddedHeader($name, $value); /** * 返回被移除掉指定報頭信息的 HTTP 消息實例。 * * 報頭信息字段在解析的時候，**必須** 保證是不區分大小寫的。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息對象，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @param string $name 不區分大小寫的頭部字段名稱。 * @return self */ public function withoutHeader($name); /** * 獲取 HTTP 消息的內容。 * * @return StreamInterface 以數據流的形式返回。 */ public function getBody(); /** * 返回指定內容的 HTTP 消息實例。 * * 內容 **必須** 是 `StreamInterface` 接口的實例。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息對象，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @param StreamInterface $body 數據流形式的內容。 * @return self * @throws \InvalidArgumentException 當消息內容不正確的時候拋出。 */ public function withBody(StreamInterface $body); } ``` </details> <br /> <details> <summary>Psr\Http\Message\RequestInterface </summary> ``` <?php namespace Psr\Http\Message; /** * 代表客戶端向服務器發起請求的 HTTP 消息對象。 * * 根據 HTTP 規范，此接口包含以下屬性： * * - HTTP 協議版本號 * - HTTP 請求方法 * - URI * - 報頭信息 * - 消息內容 * * 在構造 HTTP 請求對象的時候，如果沒有提供 Host 信息， * 實現類庫 **必須** 從給出的 URI 中去提取 Host 信息。 * * HTTP 請求是被視為無法修改的，所有能修改狀態的方法，都 **必須** 有一套機制，在內部保 * 持好原有的內容，然后把修改狀態后的新的 HTTP 請求實例返回。 */ interface RequestInterface extends MessageInterface { /** * 獲取消息的請求目標。 * * 獲取消息的請求目標的使用場景，可能是在客戶端，也可能是在服務器端，也可能是在指定信息的時候 * （參閱下方的 `withRequestTarget()`）。 * * 在大部分情況下，此方法會返回組合 URI 的原始形式，除非被指定過（參閱下方的 `withRequestTarget()`）。 * * 如果沒有可用的 URI，并且沒有設置過請求目標，此方法 **必須** 返回 「/」。 * * @return string */ public function getRequestTarget(); /** * 返回一個指定目標的請求實例。 * * 如果請求需要非原始形式的請求目標——例如指定絕對形式、認證形式或星號形式——則此方法 * 可用于創建指定請求目標的實例。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 請求實例，然后返回 * 一個新的修改過的 HTTP 請求實例。 * * @see [http://tools.ietf.org/html/rfc7230#section-2.7](http://tools.ietf.org/html/rfc7230#section-2.7) * （關于請求目標的各種允許的格式） * * @param mixed $requestTarget * @return self */ public function withRequestTarget($requestTarget); /** * 獲取當前請求使用的 HTTP 方法 * * @return string HTTP 方法字符串 */ public function getMethod(); /** * 返回更改了請求方法的消息實例。 * * 雖然，在大部分情況下，HTTP 請求方法都是使用大寫字母來標示的，但是，實現類庫 **不應該** * 修改用戶傳參的大小格式。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 請求實例，然后返回 * 一個新的修改過的 HTTP 請求實例。 * * @param string $method 大小寫敏感的方法名 * @return self * @throws \InvalidArgumentException 當非法的 HTTP 方法名傳入時會拋出異常。 */ public function withMethod($method); /** * 獲取 URI 實例。 * * 此方法 **必須** 返回 `UriInterface` 的 URI 實例。 * * @see http://tools.ietf.org/html/rfc3986#section-4.3 * @return UriInterface 返回與當前請求相關的 `UriInterface` 類型的 URI 實例。 */ public function getUri(); /** * 返回修改了 URI 的消息實例。 * * 當傳入的 URI 包含有 HOST 信息時，此方法 **必須** 更新 HOST 信息。如果 URI * 實例沒有附帶 HOST 信息，任何之前存在的 HOST 信息 **必須** 作為候補，應用 * 更改到返回的消息實例里。 * * 你可以通過傳入第二個參數來，來干預方法的處理，當 `$preserveHost` 設置為 `true` * 的時候，會保留原來的 HOST 信息。當 `$preserveHost` 設置為 `true` 時，此方法 * 會如下處理 HOST 信息： * * - 如果 HOST 信息不存在或為空，并且新 URI 包含 HOST 信息，則此方法 **必須** 更新返回請求中的 HOST 信息。 * - 如果 HOST 信息不存在或為空，并且新 URI 不包含 HOST 信息，則此方法 **不得** 更新返回請求中的 HOST 信息。 * - 如果HOST 信息存在且不為空，則此方法 **不得** 更新返回請求中的 HOST 信息。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 請求實例，然后返回 * 一個新的修改過的 HTTP 請求實例。 * * @see http://tools.ietf.org/html/rfc3986#section-4.3 * @param UriInterface $uri `UriInterface` 新的 URI 實例 * @param bool $preserveHost 是否保留原有的 HOST 頭信息 * @return self */ public function withUri(UriInterface $uri, $preserveHost = false); } ``` </details> <br /> <details> <summary>Psr\Http\Message\ServerRequestInterface </summary> ``` <?php namespace Psr\Http\Message; /** * 表示服務器端接收到的 HTTP 請求。 * * 根據 HTTP 規范，此接口包含以下屬性： * * - HTTP 協議版本號 * - HTTP 請求方法 * - URI * - 報頭信息 * - 消息內容 * * 此外，它封閉了從 CGI 和/或 PHP 環境變量，包括： * * - `$_SERVER` 中表示的值。 * - 提供的任意 Cookie 信息（通常通過 `$_COOKIE` 獲取） * - 查詢字符串參數（通常通過 `$_GET` 獲取，或者通過 `parse_str()` 解析） * - 如果存在的話，上傳文件的信息（通常通過 `$_FILES` 獲取） * - 反序列化的消息體參數（通常來自于 `$_POST`） * * `$_SERVER` 的值 **必須** 被視為不可變的，因為代表了請求時應用程序的狀態；因此，沒有允許修改的方法。 * 其他值則提供了修改的方法，因為可以從 `$_SERVER` 或請求體中恢復，并且可能在應用程序中被處理 * （比如可能根據內容類型對消息體參數進行反序列化）。 * * 此外，這個接口要識別請求的擴展信息和匹配其他的參數。 * （例如，通過 URI 進行路徑匹配，解析 Cookie 值，反序列化非表單編碼的消息體，報頭中的用戶名進行匹配認證） * 這些參數存儲在「attributes」中。 * * HTTP 請求是被視為無法修改的，所有能修改狀態的方法，都 **必須** 有一套機制，在內部保 * 持好原有的內容，然后把修改狀態后的，新的 HTTP 請求實例返回。 */ interface ServerRequestInterface extends RequestInterface { /** * 返回服務器參數。 * * 返回與請求環境相關的數據，通常從 PHP 的 `$_SERVER` 超全局變量中獲取，但不是必然的。 * * @return array */ public function getServerParams(); /** * 獲取 Cookie 數據。 * * 獲取從客戶端發往服務器的 Cookie 數據。 * * 這個數據的結構 **必須** 和超全局變量 `$_COOKIE` 兼容。 * * @return array */ public function getCookieParams(); /** * 返回具體指定 Cookie 的實例。 * * 這個數據不是一定要來源于 `$_COOKIE`，但是 **必須** 與之結構兼容。通常在實例化時注入。 * * 這個方法 **禁止** 更新實例中的 Cookie 報頭和服務器參數中的相關值。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息實例，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @param array $cookies 表示 Cookie 的鍵值對。 * @return self */ public function withCookieParams(array $cookies); /** * 獲取查詢字符串參數。 * * 如果可以的話，返回反序列化的查詢字符串參數。 * * 注意：查詢參數可能與 URI 或服務器參數不同步。如果你需要確保只獲取原始值，則可能需要調用 * `getUri()->getQuery()` 或服務器參數中的 `QUERY_STRING` 獲取原始的查詢字符串并自行解析。 * * @return array */ public function getQueryParams(); /** * 返回具體指定查詢字符串參數的實例。 * * 這些值 **應該** 在傳入請求的閉包中保持不變。它們 **可能** 在實例化的時候注入， * 例如來自 `$_GET` 或者其他一些值（例如 URI）中得到。如果是通過解析 URI 獲取，則 * 數據結構必須與 `parse_str()` 返回的內容兼容，以便處理查詢參數、嵌套的代碼可以復用。 * * 設置查詢字符串參數 **不得** 更改存儲的 URI 和服務器參數中的值。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息實例，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @param array $query 查詢字符串參數數組，通常來源于 `$_GET`。 * @return self */ public function withQueryParams(array $query); /** * 獲取規范化的上傳文件數據。 * * 這個方法會規范化返回的上傳文件元數據樹結構，每個葉子結點都是 `Psr\Http\Message\UploadedFileInterface` 實例。 * * 這些值 **可能** 在實例化的時候從 `$_FILES` 或消息體中獲取，或者通過 `withUploadedFiles()` 獲取。 * * @return array `UploadedFileInterface` 的實例數組；如果沒有數據則必須返回一個空數組。 */ public function getUploadedFiles(); /** * 返回使用指定的上傳文件數據的新實例。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息實例，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @param array `UploadedFileInterface` 實例的樹結構，類似于 `getUploadedFiles()` 的返回值。 * @return self * @throws \InvalidArgumentException 如果提供無效的結構時拋出。 */ public function withUploadedFiles(array $uploadedFiles); /** * 獲取請求消息體中的參數。 * * 如果請求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data 且請求方法是 POST， * 則此方法 **必須** 返回 $_POST 的內容。 * * 如果是其他情況，此方法可能返回反序列化請求正文內容的任何結果；當解析返回返回的結構化內容時，潛在的類型 **必須** * 只能是數組或 `object` 類型。`null` 表示沒有消息體內容。 * * @return null|array|object 如果存在則返回反序列化消息體參數。一般是一個數組或 `object`。 */ public function getParsedBody(); /** * 返回具有指定消息體參數的實例。 * * **可能** 在實例化時注入。 * * 如果請求的 Content-Type 是 application/x-www-form-urlencoded 或 multipart/form-data 且請求方法是 POST， * 則方法的參數只能是 $_POST。 * * 數據不一定要來自 $_POST，但是 **必須** 是反序列化請求正文內容的結果。由于需要反序列化/解析返回的結構化數據， * 所以這個方法只接受數組、 `object` 類型和 `null`（如果沒有可用的數據解析）。 * * 例如，如果確定請求數據是一個 JSON，可以使用此方法創建具有反序列化參數的請求實例。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息實例，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @param null|array|object $data 反序列化的消息體數據，通常是數組或 `object`。 * @return self * @throws \InvalidArgumentException 如果提供的數據類型不支持。 */ public function withParsedBody($data); /** * 獲取從請求派生的屬性。 * * 請求「attributes」可用于從請求導出的任意參數：比如路徑匹配操作的結果；解密 Cookie 的結果； * 反序列化非表單編碼的消息體的結果；屬性將是應用程序與請求特定的，并且可以是可變的。 * * @return mixed[] 從請求派生的屬性。 */ public function getAttributes(); /** * 獲取單個派生的請求屬性。 * * 獲取 getAttributes() 中聲明的某一個屬性，如果不存在則返回提供的默認值。 * * 這個方法不需要 hasAttribute 方法，因為允許在找不到指定屬性的時候返回默認值。 * * @see getAttributes() * @param string $name 屬性名稱。 * @param mixed $default 如果屬性不存在時返回的默認值。 * @return mixed */ public function getAttribute($name, $default = null); /** * 返回具有指定派生屬性的實例。 * * 此方法允許設置 getAttributes() 中聲明的單個派生的請求屬性。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息實例，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @see getAttributes() * @param string $name 屬性名。 * @param mixed $value 屬性值。 * @return self */ public function withAttribute($name, $value); /** * 返回移除指定屬性的實例。 * * 此方法允許移除 getAttributes() 中聲明的單個派生的請求屬性。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息實例，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @see getAttributes() * @param string $name 屬性名。 * @return self */ public function withoutAttribute($name); } ``` </details> <br /> <details> <summary>Psr\Http\Message\ResponseInterface</summary> ``` <?php namespace Psr\Http\Message; /** * 表示服務器返回的響應消息。 * * 根據 HTTP 規范，此接口包含以下各項的屬性： * * - 協議版本 * - 狀態碼和原因短語 * - 報頭 * - 消息體 * * HTTP 響應是被視為無法修改的，所有能修改狀態的方法，都 **必須** 有一套機制，在內部保 * 持好原有的內容，然后把修改狀態后的，新的 HTTP 響應實例返回。 */ interface ResponseInterface extends MessageInterface { /** * 獲取響應狀態碼。 * * 狀態碼是一個三位整數，用于理解請求。 * * @return int 狀態碼。 */ public function getStatusCode(); /** * 返回具有指定狀態碼和原因短語（可選）的實例。 * * 如果未指定原因短語，實現代碼 **可能** 選擇 RFC7231 或 IANA 為狀態碼推薦的原因短語。 * * 此方法在實現的時候，**必須** 保留原有的不可修改的 HTTP 消息實例，然后返回 * 一個新的修改過的 HTTP 消息實例。 * * @see http://tools.ietf.org/html/rfc7231#section-6 * @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml * @param int $code 三位整數的狀態碼。 * @param string $reasonPhrase 為狀態碼提供的原因短語；如果未提供，實現代碼可以使用 HTTP 規范建議的默認代碼。 * @return self * @throws \InvalidArgumentException 如果傳入無效的狀態碼，則拋出。 */ public function withStatus($code, $reasonPhrase = ''); /** * 獲取與響應狀態碼關聯的響應原因短語。 * * 因為原因短語不是響應狀態行中的必需元素，所以原因短語 **可能** 是空。 * 實現代碼可以選擇返回響應的狀態代碼的默認 RFC 7231 推薦原因短語（或 IANA HTTP 狀態碼注冊表中列出的原因短語）。 * * @see http://tools.ietf.org/html/rfc7231#section-6 * @see http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml * @return string 原因短語；如果不存在，則 **必須** 返回空字符串。 */ public function getReasonPhrase(); } ``` </details> <br /> <details> <summary>Psr\Http\Message\StreamInterface </summary> ``` <?php namespace Psr\Http\Message; /** * 描述數據流。 * * 通常，實例將包裝PHP流; 此接口提供了最常見操作的包裝，包括將整個流序列化為字符串。 */ interface StreamInterface { /** * 從頭到尾將流中的所有數據讀取到字符串。 * * 這個方法 **必須** 在開始讀數據前定位到流的開頭，并讀取出所有的數據。 * * 警告：這可能會嘗試將大量數據加載到內存中。 * * 這個方法 **不得** 拋出異常以符合 PHP 的字符串轉換操作。 * * @see http://php.net/manual/en/language.oop5.magic.php#object.tostring * @return string */ public function __toString(); /** * 關閉流和任何底層資源。 * * @return void */ public function close(); /** * 從流中分離任何底層資源。 * * 分離之后，流處于不可用狀態。 * * @return resource|null 如果存在的話，返回底層 PHP 流。 */ public function detach(); /** * 如果可知，獲取流的數據大小。 * * @return int|null 如果可知，返回以字節為單位的大小，如果未知返回 `null`。 */ public function getSize(); /** * 返回當前讀/寫的指針位置。 * * @return int 指針位置。 * @throws \RuntimeException 產生錯誤時拋出。 */ public function tell(); /** * 返回是否位于流的末尾。 * * @return bool */ public function eof(); /** * 返回流是否可隨機讀取。 * * @return bool */ public function isSeekable(); /** * 定位流中的指定位置。 * * @see http://www.php.net/manual/en/function.fseek.php * @param int $offset 要定位的流的偏移量。 * @param int $whence 指定如何根據偏移量計算光標位置。有效值與 PHP 內置函數 `fseek()` 相同。 * SEEK_SET：設定位置等于 $offset 字節。默認。 * SEEK_CUR：設定位置為當前位置加上 $offset。 * SEEK_END：設定位置為文件末尾加上 $offset （要移動到文件尾之前的位置，offset 必須是一個負值）。 * @throws \RuntimeException 失敗時拋出。 */ public function seek($offset, $whence = SEEK_SET); /** * 定位流的起始位置。 * * 如果流不可以隨機訪問，此方法將引發異常；否則將執行 seek(0)。 * * @see seek() * @see http://www.php.net/manual/en/function.fseek.php * @throws \RuntimeException 失敗時拋出。 */ public function rewind(); /** * 返回流是否可寫。 * * @return bool */ public function isWritable(); /** * 向流中寫數據。 * * @param string $string 要寫入流的數據。 * @return int 返回寫入流的字節數。 * @throws \RuntimeException 失敗時拋出。 */ public function write($string); /** * 返回流是否可讀。 * * @return bool */ public function isReadable(); /** * 從流中讀取數據。 * * @param int $length 從流中讀取最多 $length 字節的數據并返回。如果數據不足，則可能返回少于 * $length 字節的數據。 * @return string 返回從流中讀取的數據，如果沒有可用的數據則返回空字符串。 * @throws \RuntimeException 失敗時拋出。 */ public function read($length); /** * 返回字符串中的剩余內容。 * * @return string * @throws \RuntimeException 如果無法讀取則拋出異常。 * @throws \RuntimeException 如果在讀取時發生錯誤則拋出異常。 */ public function getContents(); /** * 獲取流中的元數據作為關聯數組，或者檢索指定的鍵。 * * 返回的鍵與從 PHP 的 stream_get_meta_data() 函數返回的鍵相同。 * * @see http://php.net/manual/en/function.stream-get-meta-data.php * @param string $key 要檢索的特定元數據。 * @return array|mixed|null 如果沒有鍵，則返回關聯數組。如果提供了鍵并且找到值， * 則返回特定鍵值；如果未找到鍵，則返回 null。 */ public function getMetadata($key = null); } ``` </details> <br /> <details> <summary>Psr\Http\Message\UriInterface</summary> ``` <?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(); } ``` </details> <br /> <details> <summary>Psr\Http\Message\UploadedFileInterface</summary> ``` <?php namespace Psr\Http\Message; /** * 通過 HTTP 請求上傳的一個文件內容。 * * 此接口的實例是被視為無法修改的，所有能修改狀態的方法，都 **必須** 有一套機制，在內部保 * 持好原有的內容，然后把修改狀態后的，新的實例返回。 */ interface UploadedFileInterface { /** * 獲取上傳文件的數據流。 * * 此方法必須返回一個 `StreamInterface` 實例，此方法的目的在于允許 PHP 對獲取到的數 * 據流直接操作，如 stream_copy_to_stream() 。 * * 如果在調用此方法之前調用了 `moveTo()` 方法，此方法 **必須** 拋出異常。 * * @return StreamInterface 上傳文件的數據流 * @throws \RuntimeException 沒有數據流的情形下。 * @throws \RuntimeException 無法創建數據流。 */ public function getStream(); /** * 把上傳的文件移動到新目錄。 * * 此方法保證能同時在 `SAPI` 和 `non-SAPI` 環境下使用。實現類庫 **必須** 判斷 * 當前處在什么環境下，并且使用合適的方法來處理，如 move_uploaded_file(), rename() * 或者數據流操作。 * * $targetPath 可以是相對路徑，也可以是絕對路徑，使用 rename() 解析起來應該是一樣的。 * * 當這一次完成后，原來的文件 **必須** 會被移除。 * * 如果此方法被調用多次，一次以后的其他調用，都要拋出異常。 * * 如果在 SAPI 環境下的話，$_FILES 內有值，當使用 moveTo(), is_uploaded_file() * 和 move_uploaded_file() 方法來移動文件時 **應該** 確保權限和上傳狀態的準確性。 * * 如果你希望操作數據流的話，請使用 `getStream()` 方法，因為在 SAPI 場景下，無法 * 保證書寫入數據流目標。 * * @see http://php.net/is_uploaded_file * @see http://php.net/move_uploaded_file * @param string $targetPath 目標文件路徑。 * @throws \InvalidArgumentException 參數有問題時拋出異常。 * @throws \RuntimeException 發生任何錯誤，都拋出此異常。 * @throws \RuntimeException 多次運行，也拋出此異常。 */ public function moveTo($targetPath); /** * 獲取文件大小。 * * 實現類庫 **應該** 優先使用 $_FILES 里的 `size` 數值。 * * @return int|null 以 bytes 為單位，或者 null 未知的情況下。 */ public function getSize(); /** * 獲取上傳文件時出現的錯誤。 * * 返回值 **必須** 是 PHP 的 UPLOAD_ERR_XXX 常量。 * * 如果文件上傳成功，此方法 **必須** 返回 UPLOAD_ERR_OK。 * * 實現類庫 **必須** 返回 $_FILES 數組中的 `error` 值。 * * @see http://php.net/manual/en/features.file-upload.errors.php * @return int PHP 的 UPLOAD_ERR_XXX 常量。 */ public function getError(); /** * 獲取客戶端上傳的文件的名稱。 * * 永遠不要信任此方法返回的數據，客戶端有可能發送了一個惡意的文件名來攻擊你的程序。 * * 實現類庫 **應該** 返回存儲在 $_FILES 數組中 `name` 的值。 * * @return string|null 用戶上傳的名字，或者 null 如果沒有此值。 */ public function getClientFilename(); /** * 客戶端提交的文件類型。 * * 永遠不要信任此方法返回的數據，客戶端有可能發送了一個惡意的文件類型名稱來攻擊你的程序。 * * 實現類庫 **應該** 返回存儲在 $_FILES 數組中 `type` 的值。 * * @return string|null 用戶上傳的類型，或者 null 如果沒有此值。 */ public function getClientMediaType(); } ``` </details> <br />