PHP Guzzle HTTP 請求庫使用方法快速入門 – 可以替代 WP HTTP API 使用

發(fā)布于：
更新時間：2025-07-16

本文介紹了PHP中廣泛使用的Guzzle HTTP請求庫，它已成為PHP語言中的HTTP標(biāo)準(zhǔn)庫。文章詳細(xì)講解了如何創(chuàng)建客戶端、發(fā)送請求以及設(shè)置基礎(chǔ)URI等操作，幫助開發(fā)者快速上手Guzzle，替代傳統(tǒng)的WP HTTP API進(jìn)行更高效的開發(fā)。

Guzzle 幾乎成為了 PHP 語言中事實(shí)上的 HTTP 標(biāo)準(zhǔn)庫，WordPress 在新版本的 JSON API 插件中，已經(jīng)棄用了 WP HTTP API ，而使用 Guzzle 進(jìn)行開發(fā)，指不定哪一天 WP HTTP API 會被徹底啟用，轉(zhuǎn)而全面使用 Guzzle，如果你以前沒有接觸過 Guzzle，下面是一些快速入門以及列子。

發(fā)送請求

我們可以使用 Guzzle 的 GuzzleHttpClientInterface 對象來發(fā)送請求。

創(chuàng)建客戶端

use GuzzleHttpClient;

$client = new Client([
    'base_uri' => 'http://httpbin.org',   // 相對請求的基礎(chǔ) URI 
    'timeout'  => 2.0,  // 可以設(shè)置請求的默認(rèn)超時時間 
]);

客戶端在 Guzzle 中是不可變的，這意味著在創(chuàng)建客戶端后，您無法更改客戶端使用的默認(rèn)值。Client 對象可以接收一個包含參數(shù)的數(shù)組：

base_uri 基礎(chǔ) URI

(string|UriInterface) 基 URI 用來合并到相關(guān) URI，可以是一個字符串或者 UriInterface 的實(shí)例，當(dāng)提供了相關(guān) URL，將合并到基 URI，遵循的規(guī)則請參考 RFC 3986, section 2 章節(jié)。

// 使用 基礎(chǔ) URI 創(chuàng)建一個客戶端
$client = new GuzzleHttpClient(['base_uri' => 'https://foo.com/api/']);

// 發(fā)送一個請求到 https://foo.com/api/test
$response = $client->request('GET', 'test');

// 發(fā)送一個請求到 https://foo.com/root
$response = $client->request('GET', '/root');

不想閱讀 RFC 3986？這里有一些關(guān)于 base_uri 與其他 URI 處理器的快速例子：

base_uriURIResult
http://foo.com/barhttp://foo.com/bar
http://foo.com/foo/barhttp://foo.com/bar
http://foo.com/foobarhttp://foo.com/bar
http://foo.com/foo/barhttp://foo.com/foo/bar
http://foo.comhttp://baz.comhttp://baz.com
http://foo.com/?barbarhttp://foo.com/bar

handler

傳輸 HTTP 請求的(回調(diào))函數(shù)。 該函數(shù)被調(diào)用的時候包含 Psr7HttpMessageRequestInterface 以及參數(shù)數(shù)組，必須返回 GuzzleHttpPromisePromiseInterface ，成功時滿足 Psr7HttpMessageResponseInterface 。 handler 是一個構(gòu)造方法，不能在請求參數(shù)里被重寫。

(混合) 構(gòu)造方法中傳入的其他所有參數(shù)用來當(dāng)作每次請求的默認(rèn)參數(shù)。

發(fā)送請求

Client 對象的方法可以很容易的發(fā)送請求：

$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');

你可以創(chuàng)建一個請求，一切就緒后將請求傳送給 Client：

use GuzzleHttpPsr7Request;

$request  = new Request('PUT', 'http://httpbin.org/put'); 
$response = $client->send($request, ['timeout' => 2]);

Client 對象為傳輸請求提供了非常靈活的處理器方式，包括請求參數(shù)、每次請求使用的中間件以及傳送多個相關(guān)請求的基URI。

你可以在 Handlers and Middleware 頁面找到更多關(guān)于中間件的內(nèi)容。

異步請求

你可以使用 Client 提供的方法來創(chuàng)建異步請求：

$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() 方法：

use GuzzleHttpPsr7Request;

// 創(chuàng)建要發(fā)送的 PSR-7 請求對象
$headers = ['X-Foo' => 'Bar'];
$body = 'Hello!';
$request = new Request('HEAD', 'http://httpbin.org/head', $headers, $body);

// 或者，如果您不需要傳入請求實(shí)例：
$promise = $client->requestAsync('GET', 'http://httpbin.org/get');

這些方法返回了 Promise 對象，該對象實(shí)現(xiàn)了由 Guzzle promises library 提供的 Promises/A+ spec ，這意味著你可以使用 then() 來調(diào)用返回值，成功使用 PsrHttpMessageResponseInterface 處理器，否則拋出一個異常。

use PsrHttpMessageResponseInterface;
use GuzzleHttpExceptionRequestException;

$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();
    }
);

并發(fā)請求

你可以使用 Promise 和異步請求來同時發(fā)送多個請求：

use GuzzleHttpClient;
use GuzzleHttpPromise;

$client = new Client(['base_uri' => 'http://httpbin.org/']);

// 開始每個請求，但是不阻塞
$promises = [
    'image' => $client->getAsync('/image'),
    'png'   => $client->getAsync('/image/png'),
    'jpeg'  => $client->getAsync('/image/jpeg'),
    'webp'  => $client->getAsync('/image/webp')
];

// 等待所有請求完成
$results = Promiseunwrap($promises);

// 您可以使用提供給 unwrap 函數(shù)的鍵來訪問每個結(jié)果。
echo $results['image']->getHeader('Content-Length');
echo $results['png']->getHeader('Content-Length');

當(dāng)你想發(fā)送不確定數(shù)量的請求時，可以使用 GuzzleHttpPool 對象：

use GuzzleHttpPool;
use GuzzleHttpClient;
use GuzzleHttpPsr7Request;

$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, $index) {
        // 每個請求成功時執(zhí)行
    },
    'rejected' => function ($reason, $index) {
        // 每個請求失敗時執(zhí)行
    },
]);

// 開始傳輸并創(chuàng)建一個 promise
$promise = $pool->promise();

// 等待請求池完成
$promise->wait();

使用響應(yīng)

前面的例子里，我們?nèi)〉搅?$response 變量，或者從 Promise 得到了響應(yīng)，Response 對象實(shí)現(xiàn)了一個 PSR-7 接口PsrHttpMessageResponseInterface ，包含了很多有用的信息。

你可以獲取這個響應(yīng)的狀態(tài)碼和和原因短語 (reason phrase)：

$code = $response->getStatusCode(); // 200
$reason = $response->getReasonPhrase(); // OK

你可以從響應(yīng)獲取頭信息 (header)：

// 檢查 header 是否存在
if ($response->hasHeader('Content-Length')) {
    echo "It exists";
}

// 從響應(yīng)中獲取請求
echo $response->getHeader('Content-Length');

// 獲取所有響應(yīng)頭
foreach ($response->getHeaders() as $name => $values) {
    echo $name . ': ' . implode(', ', $values) . "rn";
}

使用 getBody 方法可以獲取響應(yīng)的 Body，Body可以當(dāng)成一個字符串或流對象使用：

$body = $response->getBody();

// 直接作為字符串顯示 body
echo $body;

// 作為一個字符串賦值 body 給一個變量
$stringBody = (string) $body;

// 讀取 body 內(nèi)容的前 10 字節(jié)
$tenBytes = $body->read(10);

// 作為字符串讀取剩下的 body 內(nèi)容Read
$remainingBytes = $body->getContents();

查詢字符串參數(shù)

你可以有多種方式來提供請求的查詢字符串，你可以在請求的 URI 中設(shè)置查詢字符串：

$response = $client->request('GET', 'http://httpbin.org?foo=bar');

你可以使用 query 請求參數(shù)來聲明查詢字符串參數(shù)：

$client->request('GET', 'http://httpbin.org', [
    'query' => ['foo' => 'bar']
]);

提供的數(shù)組參數(shù)將會使用 PHP 的 http_build_query ：

最后，你可以提供一個字符串作為 query 請求參數(shù)：

$client->request('GET', 'http://httpbin.org', ['query' => 'foo=bar']);

上傳數(shù)據(jù)

Guzzle 為上傳數(shù)據(jù)提供了一些方法。 你可以發(fā)送一個包含數(shù)據(jù)流的請求，將 body 請求參數(shù)設(shè)置成一個字符串、fopen 返回的資源、或者一個 PsrHttpMessageStreamInterface 的實(shí)例。

// 作為字符串提供 body 內(nèi)容
$r = $client->request('POST', 'http://httpbin.org/post', [
    'body' => 'raw data'
]);

// 提供一個 fopen 資源
$body = fopen('/path/to/file', 'r');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

// 使用 stream_for() 函數(shù)創(chuàng)建一個 PSR-7 stream.
$body = GuzzleHttpPsr7stream_for('hello!');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

上傳 JSON 數(shù)據(jù)以及設(shè)置合適的頭信息可以使用 json 請求參數(shù)這個簡單的方式：

$r = $client->request('PUT', 'http://httpbin.org/put', [
    'json' => ['foo' => 'bar']
]);

POST/表單請求

除了使用 body 參數(shù)來指定請求數(shù)據(jù)外，Guzzle 為發(fā)送 POST 數(shù)據(jù)提供了有用的方法。

發(fā)送表單字段

發(fā)送 application/x-www-form-urlencoded POST 請求需要你傳入 form_params 數(shù)組參數(shù)，數(shù)組內(nèi)指定 POST 的字段。

$response = $client->request('POST', 'http://httpbin.org/post', [
    'form_params' => [
        'field_name' => 'abc',
        'other_field' => '123',
        'nested_field' => [
            'nested' => 'hello'
        ]
    ]
]);

發(fā)送表單文件

你可以通過使用 multipart 請求參數(shù)來發(fā)送表單(表單enctype屬性需要設(shè)置 multipart/form-data )文件， 該參數(shù)接收一個包含多個關(guān)聯(lián)數(shù)組的數(shù)組，每個關(guān)聯(lián)數(shù)組包含一下鍵名：

  • name: (必須，字符串) 映射到表單字段的名稱。
  • contents: (必須，混合) 提供一個字符串，可以是 fopen 返回的資源、或者一個

PsrHttpMessageStreamInterface 的實(shí)例。

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 請求參數(shù)為你維護(hù)一個 Cookie會話，當(dāng)發(fā)送一個請求時， Cookies 選項(xiàng)必須設(shè)置成 GuzzleHttpCookieCookieJarInterface 的實(shí)例。

// 使用一個指定的 cookie
$jar = new GuzzleHttpCookieCookieJar;
$r = $client->request('GET', 'http://httpbin.org/cookies', [
    'cookies' => $jar
]);

如果你想在所有的請求中共享 Cookies, 你可以在客戶端構(gòu)造器中設(shè)置 Cookies 為 true。

// 使用共 cookie 的客戶端
$client = new GuzzleHttpClient(['cookies' => true]);
$r = $client->request('GET', 'http://httpbin.org/cookies');

重定向

如果你沒有告訴 Guzzle 不要重定向，Guzzle 會自動的進(jìn)行重定向，你可以使用 allow_redirects 請求參數(shù)來自定義重定向行為。

  • 設(shè)置成 true 時將啟用最大數(shù)量為5的重定向，這是默認(rèn)設(shè)置。
  • 設(shè)置成 false 來禁用重定向。
  • 傳入一個包含 max 鍵名的關(guān)聯(lián)數(shù)組來聲明最大重定向次數(shù)，提供可選的 strict 鍵名來聲明是否使用嚴(yán)格的 RFC 標(biāo)準(zhǔn)重定向 (表示使用 POST 請求重定向 POST 請求 vs 大部分瀏覽器使用GET請求重定向 POST 請求)。
$response = $client->request('GET', 'http://github.com');

echo $response->getStatusCode();  // 200

下面的列子表示重定向被禁止：

$response = $client->request('GET', 'http://github.com', [
    'allow_redirects' => false
]);

echo $response->getStatusCode();

異常

請求傳輸過程中出現(xiàn)的錯誤 Guzzle 將會拋出異常。

  • 在發(fā)送網(wǎng)絡(luò)錯誤(連接超時、DNS 錯誤等)時，將會拋出 GuzzleHttpExceptionRequestException 異常。 該異常繼承自 GuzzleHttpExceptionTransferException ，捕獲這個異?？梢栽趥鬏斦埱筮^程中拋出異常。
    use GuzzleHttpExceptionRequestException;

    try {
        $client->request('GET', 'https://github.com/_abc_123_404');
    } catch (RequestException $e) {
        echo $e->getRequest();
        if ($e->hasResponse()) {
            echo $e->getResponse();
        }
    }
  • GuzzleHttpExceptionConnectException 異常發(fā)生在網(wǎng)絡(luò)錯誤時， 該異常繼承自 GuzzleHttpExceptionRequestException 。
  • 如果 http_errors 請求參數(shù)設(shè)置成 true，在 400 級別的錯誤的時候?qū)伋?GuzzleHttpExceptionClientException 異常， 該異常繼承自 GuzzleHttpExceptionBadResponseException GuzzleHttpExceptionBadResponseException 繼承自 GuzzleHttpExceptionRequestException 。
    use GuzzleHttpExceptionClientException;

    try {
        $client->request('GET', 'https://github.com/_abc_123_404');
    } catch (ClientException $e) {
        echo $e->getRequest();
        echo $e->getResponse();
    }
  • 如果 http_errors 請求參數(shù)設(shè)置成 true，在 500 級別的錯誤的時候?qū)伋?GuzzleHttpExceptionServerException 異常。 該異常繼承自 GuzzleHttpExceptionBadResponseException 。
  • GuzzleHttpExceptionTooManyRedirectsException 異常發(fā)生在重定向次數(shù)過多時， 該異常繼承自 GuzzleHttpExceptionRequestException 。

上述所有異常均繼承自 GuzzleHttpExceptionTransferException 。

環(huán)境變量

Guzzle 提供了一些可自定義的環(huán)境變量：

GUZZLE_CURL_SELECT_TIMEOUT

當(dāng)在 Curl 處理器時使用 curl_multi_select() 控制了 curl_multi_* 需要使用到的持續(xù)時間， 有些系統(tǒng)實(shí)現(xiàn) PHP 的 curl_multi_select() 存在問題，調(diào)用該函數(shù)時總是等待超時的最大值。

HTTP_PROXY

定義了使用 Http 協(xié)議發(fā)送請求時使用的代理。

HTTPS_PROXY

定義了使用 Https 協(xié)議發(fā)送請求時使用的代理。

一刀（WordPress智庫站長）

我們提供 WordPress主題和插件定制開發(fā)服務(wù)

本站長期承接 WordPress主題、插件、基于 WooCommerce 的商店商城開發(fā)業(yè)務(wù)。 我們有 10 年WordPress開發(fā)經(jīng)驗(yàn)，如果你想 用WordPress開發(fā)網(wǎng)站, 請聯(lián)系微信: iwillhappy1314，或郵箱: [email protected] 咨詢。

發(fā)表回復(fù)

您的郵箱地址不會被公開。 必填項(xiàng)已用 * 標(biāo)注

*