HTTP 請求 · Slim3 中文文檔

# HTTP 請求 Slim 應用程序的路由和中間件給出了一個 PSR 7 請求對象，它表示當前的 HTTP 請求是由 Web 服務器接收到的。該請求對象遵循 [PSR 7 服務器請求接口（ServerRequestInterface ）](http://www.php-fig.org/psr/psr-7/#3-2-1-psr-http-message-serverrequestinterface) 實現，因此你可以檢查和操作該 HTTP 請求對象的方法、頭和體。 ## 如何獲取請求對象該 PSR 7 請求對象作為路由回調的第一個參數注入到你的 Slim 應用程序的路由中，像這樣： ``` <?php use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Message\ResponseInterface; $app = new \Slim\App; $app->get('/foo', function (ServerRequestInterface $request, ResponseInterface $response) { // 使用 PSR 7 $request 對象 return $response; }); $app->run(); ``` Figure 1: 將 PSR 7 請求注入到應用程序的路由回調中。該 PSR 7 請求對象作為中間件 callable 的第一個參數注入到 Slim 應用程序的_中間件_中，像這樣： ``` <?php use Psr\Http\Message\ServerRequestInterface; use Psr\Http\Message\ResponseInterface; $app = new \Slim\App; $app->add(function (ServerRequestInterface $request, ResponseInterface $response, callable $next) { // Use the PSR 7 $request object return $next($request, $response); }); // Define app routes... $app->run(); ``` Figure 2: 注入 PSR 7 請求到應用程序中間件 ## 請求的方法每個 HTTP 請求都有相應的方法，通常是這些中的一個： * GET * POST * PUT * DELETE * HEAD * PATCH * OPTIONS 你可以恰當地使用 `getMethod()` 請求對象方法來檢查 HTTP 請求方法。 ``` $method = $request->getMethod(); ``` 由于這是一個常見的功能，Slim 的內置 PSR 7 實現方法也提供了這些專有方法，它們返回 `true` 或 `false` 。 * `$request->isGet()` * `$request->isPost()` * `$request->isPut()` * `$request->isDelete()` * `$request->isHead()` * `$request->isPatch()` * `$request->isOptions()` 還可以偽造或_覆寫_這些 HTTP 請求方法。這非常有用，例如你需要在一個只支持 `GET` 或 `POST` 請求的傳統瀏覽器中模擬一個 `PUT` 請求。有兩種方法來覆寫 HTTP 請求方法。你可以在一個 `POST` 請求體中引入（include）一個 `_METHOD` 參數。該 HTTP 請求必須使用 `application/x-www-form-urlencoded` 內容類型（content type）。 ``` POST /path HTTP/1.1 Host: example.com Content-type: application/x-www-form-urlencoded Content-length: 22 data=value&_METHOD=PUT ``` Figure 3: 使用 _METHOD 參數覆寫 HTTP 請求。你也可以使用自定義的 `X-Http-Method-Override` HTTP請求頭來覆寫 HTTP 請求方法。這個方式可以用于任意 HTTP 請求內容類型（content type）。 ``` POST /path HTTP/1.1 Host: example.com Content-type: application/json Content-length: 16 X-Http-Method-Override: PUT {"data":"value"} ``` Figure 4: 使用 X-Http-Method-Override 請求頭覆寫 HTTP 方法。你可以使用 PSR 7 請求對象的方法 `getOriginalMethod()` 來提取_原有_ （不是覆寫后的）的 HTTP 方法。 ## 請求 URI 每個 HTTP 請求都有一個識別被請求的應用程序資源的 URI 。HTTP 請求 URI 分為這幾部分： * Scheme (e.g. `http` or `https`) * Host (e.g. `example.com`) * Port (e.g. `80` or `443`) * Path (e.g. `/users/1`) * Query string (e.g. `sort=created&dir=asc`) 你可以使用 `getUri()` 方法來提取 PSR 7 請求對象的 URI ： ``` $uri = $request->getUri(); ``` PSR 7 請求對象的 URI 本身就是一個對象，提供了以下方法來檢查 HTTP 請求的 URL ： * `getScheme()` * `getAuthority()` * `getUserInfo()` * `getHost()` * `getPort()` * `getPath()` * `getBasePath()` * `getQuery()` <small>(返回整個查詢字符串，e.g. `a=1&b=2`)</small> * `getFragment()` * `getBaseUrl()` **基準路徑**如果你的 Slim 應用程序的前端控制器放置在文件根目錄的物理子目錄中，你可以使用 URI 對象的 `getBasePath()` 方法來提取 HTTP 請求的物理基準路徑（相對于文件根目錄）。如果 Slim 應用程序安裝在文件根目錄的最上層目錄中，它將返回一個空字符串。 ## 請求頭每個 HTTP 請求都有請求頭。這些元數據描述了 HTTP 請求，但在請求體中不可見。Slim 的 PSR 7 請求對象提供了幾個檢查請求頭的方法。 ### 獲取所有請求頭使用 PSR 7 請求對象的`getHeaders()`方法提取所有 HTTP 請求頭并放入一個關聯數組中。此關聯數組的鍵值是請求頭的名稱，其值是各請求頭對應的由字符串值組成的數值數組。 ``` $headers = $request->getHeaders(); foreach ($headers as $name => $values) { echo $name . ": " . implode(", ", $values); } ``` Figure 5: 提取并迭代所有 HTTP 請求頭作為一個關聯數組。 ### 獲取單個請求頭你可以使用 PSR 7 請求對象的 `getHeader($name)` 方法獲取一個單獨的請求頭的值。它將返回一個由指定請求頭名稱對應的值組成的數組。記住，單獨的請求頭可不一定只有一個值。 ``` $headerValueArray = $request->getHeader('Accept'); ``` Figure 6: 獲取指定 HTTP 請求的值。你同樣可以使用 PSR 7 請求對象的 `getHeaderLine($name)` 方法提取指定請求頭的值，并以逗號分隔。這不同于 `getHeader($name)` 方法，這個方法返回一個由逗號分隔的字符串。 ``` $headerValueString = $request->getHeaderLine('Accept'); ``` Figure 7: 獲取單個請求頭的值，返回逗號分隔的字符串。 ### 檢測請求頭使用 PSR 7 請求對象的 `hasHeader($name)` 方法檢查某請求頭是否存在。 ``` if ($request->hasHeader('Accept')) { // Do something } ``` Figure 8: Detect presence of a specific HTTP request header. ## 請求體每個 HTTP 請求都有一個請求體。如果你的 Slim 應用程序是通過 JSON 或 XML 數據進行通信的，你可以使用 PSR 7 請求對象的 `getParsedBody()` 方法將 HTTP 請求體解析成原生 PHP 格式。Slim 可以解析 JSON, XML, 和 URL-encoded 數據，開箱即用。 ``` $parsedBody = $request->getParsedBody(); ``` Figure 9: Parse HTTP request body into native PHP format * JSON 請求通過 `json_decode($input)` 轉換成 PHP 對象。 * XML 請求通過 `simplexml_load_string($input)` 轉換成 `SimpleXMLElement` 。 * URL-encoded 請求通過 `parse_str($input)` 轉換成 PHP 數組。從技術上說，Slim 的 PSR 7 請求對象將 HTTP 請求體表示為 `\Psr\Http\Message\StreamInterface` 的一個實例。你可以通過使用 PSR 7 請求對象的 `getBody()` 方法獲取 HTTP 請求體的 `StreamInterface` 實例。該 `getBody()` 方法在處理未知大小或對于可用內存來說太大的 HTTP 請求時，是個很好的方法。 ``` $body = $request->getBody(); ``` Figure 10: 獲取 HTTP 請求體生成的 `\Psr\Http\Message\StreamInterface` 實例提供了以下方法來讀取或迭代未知的 `資源（resource）`。 * `getSize()` * `tell()` * `eof()` * `isSeekable()` * `seek()` * `rewind()` * `isWritable()` * `write($string)` * `isReadable()` * `read($length)` * `getContents()` * `getMetadata($key = null)` ## 請求助手/Request Helpers Slim 的 PSR 7 請求實現方法提供了額外的專有方法來幫助你進一步檢查 HTTP 請求。 ### 檢測 XHR 請求你可以使用請求對象的 `isXhr()` 方法來檢測 XHR 請求。該方法檢測 `X-Requested-With` 請求頭，并確保它的值是 `XMLHttpRequest`。 ``` POST /path HTTP/1.1 Host: example.com Content-type: application/x-www-form-urlencoded Content-length: 7 X-Requested-With: XMLHttpRequest foo=bar ``` Figure 11: XHR 請求示例. ``` if ($request->isXhr()) { // Do something } ``` ### 內容類型/Content Type 你可以使用請求對象的 `getContentType()` 方法提取 HTTP 請求的內容類型。它將通過 HTTP 客戶端返回 `Content-Type` 頭的完整值。 ``` $contentType = $request->getContentType(); ``` ### 媒體類型/Media Type 你或許不會想要完整的 `Content-Type` 頭。加入說你只想要媒體類型？你可以使用響應對象的 `getMediaType()`方法取得 HTTP 請求的媒體類型。 ``` $mediaType = $request->getMediaType(); ``` 可以使用請求對象的 `getMediaTypeParams()` 方法，以關聯數組的形式獲取附加的沒提類型參數。 ``` $mediaParams = $request->getMediaTypeParams(); ``` ### 字符集/Character Set HTTP 請求字符集是最常用的媒體類型參數之一。請求對象提供了一個專用的方法來獲取這個媒體類型參數。 ``` $charset = $request->getContentCharset(); ``` ### 內容長度/Content Length 使用請求對象的 `getContentLength()` 方法獲取 HTTP 請求的內容長度。 ``` $length = $request->getContentLength(); ``` ### 路由對象/Route Object 有時在中間件中你需要路由的參數。在這個例子中，我們首先檢查用戶是否登錄，然后檢查用戶有否有權限瀏覽他們正試圖瀏覽的視頻。 ``` $app->get('/course/{id}', Video::class.":watch")->add(Permission::class)->add(Auth::class); //.. In the Permission Class's Invoke /** @var $route \Slim\Route */ $route = $request->getAttribute('route'); $courseId = $route->getArgument('id'); ``` ## 媒體類型解析如果 HTTP 請求的媒體類型被識別，將通過 `$request->getParsedBody()` 解析成為結構化的可用數據。通常是解析成一個數組，或者是 XML 媒體類型的對象。以下媒體類型是可識別和解析的： * application/x-www-form-urlencoded’ * application/json * application/xml & text/xml 如果你想要用 Slim 來解析其它媒體類型，那么你可以自行解析原生的 HTTP 請求體，或者新注冊一個媒體解析器。媒體解析器都是簡單的 callable ，它接收一個 `$input` 字符串并返回一個解析后的對象或數組。在應用程序或者路由中間件中注冊新的媒體解析器。注意，你必須在首次嘗試訪問解析后的 HTTP 請求體前注冊該解析器。例如，要自動解析帶有 `text/javascript` 內容類型的 JSON，你可以像這樣在中間件中注冊媒體解析器： ``` // 添加中間件 $app->add(function ($request, $response, $next) { // add media parser $request->registerMediaTypeParser( "text/javascript", function ($input) { return json_decode($input, true); } ); return $next($request, $response); }); ```