快速入門 · Guzzle 7

[TOC] 該頁面提供了Guzzle的快速入門以及列子，如果你還沒有安裝Guzzle請前往 [安裝](1998291#_9) 頁面。 ## 發送請求你可以使用Guzzle的 `GuzzleHttp\ClientInterface` 對象來發送請求。 ### 創建客戶端 ```php use GuzzleHttp\Client; $client = new Client([ // Base URI is used with relative requests 'base_uri' => 'http://httpbin.org', // You can set any number of default request options. 'timeout' => 2.0, ]); ``` Client對象可以接收一個包含參數的數組： `base_uri` (string|UriInterface) 基URI用來合并到相關URI，可以是一個字符串或者UriInterface的實例，當提供了相關uri，將合并到基URI，遵循的規則請參考 [RFC 3986, section 5.2](https://tools.ietf.org/html/rfc3986#section-5.2) 章節。 ```php // Create a client with a base URI $client = new GuzzleHttp\Client(['base_uri' => 'https://foo.com/api/']); // Send a request to https://foo.com/api/test $response = $client->request('GET', 'test'); // Send a request to https://foo.com/root $response = $client->request('GET', '/root'); ``` 不想閱讀RFC 3986？這里有一些關于 `base_uri `與其他URI處理器的快速例子： |base_uri|URI|Result| |---|---|---| |http://foo.com|/bar|http://foo.com/bar| |http://foo.com/foo|/bar|http://foo.com/bar| |http://foo.com/foo|bar|http://foo.com/bar| |http://foo.com/foo/|bar|http://foo.com/foo/bar| |http://foo.com|http://baz.com|http://baz.com| |http://foo.com/?bar|bar|http://foo.com/bar| `handler` 傳輸HTTP請求的(回調)函數。該函數被調用的時候包含 `Psr7\Http\Message\RequestInterface` 以及參數數組，必須返回 `GuzzleHttp\Promise\PromiseInterface`，成功時滿足 `Psr7\Http\Message\ResponseInterface`。 `handler`是一個構造方法，不能在請求參數里被重寫。 `...` (混合) 構造方法中傳入的其他所有參數用來當作每次請求的默認參數。 ### 發送請求 Client對象的方法可以很容易的發送請求： ```php $response = $client->get('http://httpbin.org/get'); $response = $client->delete('http://httpbin.org/delete'); $response = $client->head('http://httpbin.org/get'); $response = $client->options('http://httpbin.org/get'); $response = $client->patch('http://httpbin.org/patch'); $response = $client->post('http://httpbin.org/post'); $response = $client->put('http://httpbin.org/put'); ``` 你可以創建一個請求，一切就緒后將請求傳送給client： ```php use GuzzleHttp\Psr7\Request; $request = new Request('PUT', 'http://httpbin.org/put'); $response = $client->send($request, ['timeout' => 2]); ``` Client對象為傳輸請求提供了非常靈活的處理器方式，包括請求參數、每次請求使用的中間件以及傳送多個相關請求的基URI。你可以在 [Handlers and Middleware](https://docs.guzzlephp.org/en/stable/handlers-and-middleware.html) 頁面找到更多關于中間件的內容。 ### 異步請求你可以使用Client提供的方法來創建異步請求： ```php $promise = $client->getAsync('http://httpbin.org/get'); $promise = $client->deleteAsync('http://httpbin.org/delete'); $promise = $client->headAsync('http://httpbin.org/get'); $promise = $client->optionsAsync('http://httpbin.org/get'); $promise = $client->patchAsync('http://httpbin.org/patch'); $promise = $client->postAsync('http://httpbin.org/post'); $promise = $client->putAsync('http://httpbin.org/put'); ``` 你也可以使用Client的 sendAsync() and requestAsync() 方法： ```php use GuzzleHttp\Psr7\Request; // Create a PSR-7 request object to send $headers = ['X-Foo' => 'Bar']; $body = 'Hello!'; $request = new Request('HEAD', 'http://httpbin.org/head', $headers, $body); $promise = $client->sendAsync($request); // Or, if you don't need to pass in a request instance: $promise = $client->requestAsync('GET', 'http://httpbin.org/get'); ``` 這些方法返回了Promise對象，該對象實現了由 [Guzzle promises library](https://github.com/guzzle/promises) 提供的 [Promises/A+ spec](https://promisesaplus.com/)，這意味著你可以使用`then()`來調用返回值，成功使用`Psr\Http\Message\ResponseInterface`處理器，否則拋出一個異常。 ```php use Psr\Http\Message\ResponseInterface; use GuzzleHttp\Exception\RequestException; $promise = $client->requestAsync('GET', 'http://httpbin.org/get'); $promise->then( function (ResponseInterface $res) { echo $res->getStatusCode() . "\n"; }, function (RequestException $e) { echo $e->getMessage() . "\n"; echo $e->getRequest()->getMethod(); } ); ``` ### 并發請求你可以使用Promise和異步請求來同時發送多個請求： ```php use GuzzleHttp\Client; use GuzzleHttp\Promise; $client = new Client(['base_uri' => 'http://httpbin.org/']); // Initiate each request but do not block $promises = [ 'image' => $client->getAsync('/image'), 'png' => $client->getAsync('/image/png'), 'jpeg' => $client->getAsync('/image/jpeg'), 'webp' => $client->getAsync('/image/webp') ]; // Wait for the requests to complete; throws a ConnectException // if any of the requests fail $responses = Promise\Utils::unwrap($promises); // You can access each response using the key of the promise echo $responses['image']->getHeader('Content-Length')[0]; echo $responses['png']->getHeader('Content-Length')[0]; // Wait for the requests to complete, even if some of them fail $responses = Promise\Utils::settle($promises)->wait(); // Values returned above are wrapped in an array with 2 keys: "state" (either fulfilled or rejected) and "value" (contains the response) echo $responses['image']['state']; // returns "fulfilled" echo $responses['image']['value']->getHeader('Content-Length')[0]; echo $responses['png']['value']->getHeader('Content-Length')[0]; ``` 當你想發送不確定數量的請求時，可以使用`GuzzleHttp\Pool`對象： ```php use GuzzleHttp\Client; use GuzzleHttp\Exception\RequestException; use GuzzleHttp\Pool; use GuzzleHttp\Psr7\Request; use GuzzleHttp\Psr7\Response; $client = new Client(); $requests = function ($total) { $uri = 'http://127.0.0.1:8126/guzzle-server/perf'; for ($i = 0; $i < $total; $i++) { yield new Request('GET', $uri); } }; $pool = new Pool($client, $requests(100), [ 'concurrency' => 5, 'fulfilled' => function (Response $response, $index) { // this is delivered each successful response }, 'rejected' => function (RequestException $reason, $index) { // this is delivered each failed request }, ]); // Initiate the transfers and create a promise $promise = $pool->promise(); // Force the pool of requests to complete. $promise->wait(); ``` 或者使用一個閉包，一旦池調用閉包，它將返回一個`promise`。 ```php $client = new Client(); $requests = function ($total) use ($client) { $uri = 'http://127.0.0.1:8126/guzzle-server/perf'; for ($i = 0; $i < $total; $i++) { yield function() use ($client, $uri) { return $client->getAsync($uri); }; } }; $pool = new Pool($client, $requests(100)); ``` ## 使用響應前面的例子里，我們取到了`$response`變量，或者從Promise得到了響應，Response對象實現了一個PSR-7接口`Psr\Http\Message\ResponseInterface`，包含了很多有用的信息。你可以獲取這個響應的狀態碼和和原因短語(reason phrase)： ```php $code = $response->getStatusCode(); // 200 $reason = $response->getReasonPhrase(); // OK ``` 你可以從響應獲取頭信息(header)： ```php // Check if a header exists. if ($response->hasHeader('Content-Length')) { echo "It exists"; } // Get a header from the response. echo $response->getHeader('Content-Length'); // Get all of the response headers. foreach ($response->getHeaders() as $name => $values) { echo $name . ': ' . implode(', ', $values) . "\r\n"; } ``` 使用`getBody`方法可以獲取響應的主體部分(body)，主體可以當成一個字符串或流對象使用 ```php $body = $response->getBody(); // Implicitly cast the body to a string and echo it echo $body; // Explicitly cast the body to a string $stringBody = (string) $body; // Read 10 bytes from the body $tenBytes = $body->read(10); // Read the remaining contents of the body as a string $remainingBytes = $body->getContents(); ``` ## 查詢字符串參數你可以有多種方式來提供請求的查詢字符串你可以在請求的URI中設置查詢字符串： ```php $response = $client->request('GET', 'http://httpbin.org?foo=bar'); ``` 你可以使用`query`請求參數來聲明查詢字符串參數： ```php $client->request('GET', 'http://httpbin.org', [ 'query' => ['foo' => 'bar'] ]); ``` 提供的數組參數將會使用PHP的`http_build_query`：最后，你可以提供一個字符串作為`query`請求參數： ```php $client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']); ``` ## 上傳數據 Guzzle為上傳數據提供了一些方法。你可以發送一個包含數據流的請求，將`body`請求參數設置成一個字符串、`fopen`返回的資源、或者一個`Psr\Http\Message\StreamInterface`的實例。 ```php // Provide the body as a string. $r = $client->request('POST', 'http://httpbin.org/post', [ 'body' => 'raw data' ]); // Provide an fopen resource. $body = fopen('/path/to/file', 'r'); $r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]); // Use the Utils::streamFor method to create a PSR-7 stream. $body = \GuzzleHttp\Psr7\Utils::streamFor('hello!'); $r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]); ``` 上傳JSON數據以及設置合適的頭信息可以使用`json`請求參數這個簡單的方式： ```php $r = $client->request('PUT', 'http://httpbin.org/put', [ 'json' => ['foo' => 'bar'] ]); ``` ### POST/表單請求除了使用`body`參數來指定請求數據外，Guzzle為發送POST數據提供了有用的方法。 #### 發送表單字段發送`application/x-www-form-urlencoded`POST請求需要你傳入`form_params`數組參數，數組內指定POST的字段。 ```php $response = $client->request('POST', 'http://httpbin.org/post', [ 'form_params' => [ 'field_name' => 'abc', 'other_field' => '123', 'nested_field' => [ 'nested' => 'hello' ] ] ]); ``` #### 發送表單文件你可以通過使用`multipart`請求參數來發送表單(表單enctype屬性需要設置`multipart/form-data`)文件，該參數接收一個包含多個關聯數組的數組，每個關聯數組包含一下鍵名： * name: (必須，字符串) 映射到表單字段的名稱。 * contents: (必須，混合) 提供一個字符串，可以是`fopen`返回的資源、或者一個`Psr\Http\Message\StreamInterface`以從PSR-7流中傳輸內容。 ```php $response = $client->request('POST', 'http://httpbin.org/post', [ 'multipart' => [ [ 'name' => 'field_name', 'contents' => 'abc' ], [ 'name' => 'file_name', 'contents' => fopen('/path/to/file', 'r') ], [ 'name' => 'other_file', 'contents' => 'hello', 'filename' => 'filename.txt', 'headers' => [ 'X-Foo' => 'this is an extra header to include' ] ] ] ]); ``` ## Cookies Guzzle可以使用`cookies`請求參數為你維護一個cookie會話，當發送一個請求時，`cookies`選項必須設置成`GuzzleHttp\Cookie\CookieJarInterface`的實例。 ```php // Use a specific cookie jar $jar = new \GuzzleHttp\Cookie\CookieJar; $r = $client->request('GET', 'http://httpbin.org/cookies', [ 'cookies' => $jar ]); ``` 如果您想對所有請求使用共享的`cookie jar`，則可以在客戶端構造函數中將cookie設置為true。 ```php // Use a shared client cookie jar $client = new \GuzzleHttp\Client(['cookies' => true]); $r = $client->request('GET', 'http://httpbin.org/cookies'); ``` `GuzzleHttp\Cookie\CookieJarInterface`存在不同的實現： * `GuzzleHttp\Cookie\CookieJar`類將cookie存儲為數組。 * `GuzzleHttp\Cookie\FileCookieJar`類使用JSON格式的文件保留非會話cookie。 * `GuzzleHttp\Cookie\SessionCookieJar`類在客戶端會話中保留cookie。您可以使用命名構造函數`fromArray(array $cookies, $domain)`將cookie手動設置到cookie jar中。 ```php $jar = \GuzzleHttp\Cookie\CookieJar::fromArray( [ 'some_cookie' => 'foo', 'other_cookie' => 'barbaz1234' ], 'example.org' ); ``` 您可以使用返回`GuzzleHttp\Cookie\SetCookie`實例的`getCookieByName($name)`方法獲取其名稱的cookie。 ```php $cookie = $jar->getCookieByName('some_cookie'); $cookie->getValue(); // 'foo' $cookie->getDomain(); // 'example.org' $cookie->getExpires(); // expiration date as a Unix timestamp ``` 借助toArray()方法，也可以將cookie提取到數組中。`GuzzleHttp\Cookie\CookieJarInterface`接口擴展了`Traversable`，因此可以在foreach循環中進行迭代。 ## 重定向樹形視圖下面的樹形視圖描述了Guzzle異常如何相互依賴。 > . \RuntimeException > └── TransferException (implements GuzzleException) > └── ConnectException (implements NetworkExceptionInterface) > └── RequestException > ├── BadResponseException > │ ├── ServerException > │ └── ClientException > └── TooManyRedirectsException 如果你沒有告訴Guzzle不要重定向，Guzzle會自動的進行重定向，你可以使用`allow_redirects`請求參數來自定義重定向行為。 * 設置成`true`時將啟用最大數量為5的重定向，這是默認設置。 * 設置成`false`來禁用重定向。 * 傳入一個包含`max`鍵名的關聯數組來聲明最大重定向次數，提供可選的`strict`鍵名來聲明是否使用嚴格的RFC標準重定向 (表示使用POST請求重定向POST請求 vs 大部分瀏覽器使用GET請求重定向POST請求)。 ```php $response = $client->request('GET', 'http://github.com'); echo $response->getStatusCode(); // 200 ``` 下面的列子表示重定向被禁止： ```php $response = $client->request('GET', 'http://github.com', [ 'allow_redirects' => false ]); echo $response->getStatusCode(); // 301 ``` ## 異常請求傳輸過程中出現的錯誤Guzzle將會拋出異常。 * 在發送網絡錯誤(連接超時、DNS錯誤等)時，將會拋出`GuzzleHttp\Exception\RequestException`異常。該異常繼承自`GuzzleHttp\Exception\TransferException`，捕獲這個異常可以在傳輸請求過程中拋出異常。 ```php use GuzzleHttp\Psr7; use GuzzleHttp\Exception\RequestException; try { $client->request('GET', 'https://github.com/_abc_123_404'); } catch (RequestException $e) { echo Psr7\Message::toString($e->getRequest()); if ($e->hasResponse()) { echo Psr7\Message::toString($e->getResponse()); } } ``` * `GuzzleHttp\Exception\ConnectException`異常發生在網絡錯誤時，該異常繼承自`GuzzleHttp\Exception\RequestException`。 * 如果`http_errors`請求參數設置成true，在400級別的錯誤的時候將會拋出`GuzzleHttp\Exception\ClientException`異常，該異常繼承自`GuzzleHttp\Exception\BadResponseException` `GuzzleHttp\Exception\BadResponseException`繼承自`GuzzleHttp\Exception\RequestException`。 ```php use GuzzleHttp\Psr7; use GuzzleHttp\Exception\ClientException; try { $client->request('GET', 'https://github.com/_abc_123_404'); } catch (ClientException $e) { echo Psr7\Message::toString($e->getRequest()); echo Psr7\Message::toString($e->getResponse()); } ``` * 如果`http_errors`請求參數設置成true，在500級別的錯誤的時候將會拋出`GuzzleHttp\Exception\ServerException`異常。該異常繼承自`GuzzleHttp\Exception\BadResponseException`。 * `GuzzleHttp\Exception\TooManyRedirectsException`異常發生在重定向次數過多時，該異常繼承自`GuzzleHttp\Exception\RequestException`。上述所有異常均繼承自`GuzzleHttp\Exception\TransferException`。 ## 環境變量 Guzzle提供了一些可自定義的環境變量： `GUZZLE_CURL_SELECT_TIMEOUT` 當在curl處理器時使用`curl_multi_select()`控制了 curl_multi_* 需要使用到的持續時間，有些系統實現PHP的`curl_multi_select()`存在問題，調用該函數時總是等待超時的最大值。 `HTTP_PROXY` 定義了使用http協議發送請求時使用的代理。 `HTTPS_PROXY` 定義了使用https協議發送請求時使用的代理。 ### 相關ini設置 Guzzle配置客戶端時可以利用PHP的ini配置。 `openssl.cafile` 當發送到"https"協議的請求時需要用到指定磁盤上PEM格式的CA文件，參考：[https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults](https://wiki.php.net/rfc/tls-peer-verification#phpini_defaults)