首页 » 主题开发分享 » PHP Guzzle HTTP 请求库使用方法快速入门 – 可以替代 WP HTTP API 使用

PHP Guzzle HTTP 请求库使用方法快速入门 – 可以替代 WP HTTP API 使用

发布于：
更新时间：2025-03-20

本文介绍了PHP中广泛使用的Guzzle HTTP请求库，它已成为PHP语言中的HTTP标准库。文章详细讲解了如何创建客户端、发送请求以及设置基础URI等操作，帮助开发者快速上手Guzzle，替代传统的WP HTTP API进行更高效的开发。

Guzzle 几乎成为了 PHP 语言中事实上的 HTTP 标准库，WordPress 在新版本的 JSON API 插件中，已经弃用了 WP HTTP API ，而使用 Guzzle 进行开发，指不定哪一天 WP HTTP API 会被彻底启用，转而全面使用 Guzzle，如果你以前没有接触过 Guzzle，下面是一些快速入门以及列子。

发送请求

我们可以使用 Guzzle 的 GuzzleHttpClientInterface 对象来发送请求。

创建客户端

use GuzzleHttpClient;

$client = new Client([
    'base_uri' => 'http://httpbin.org',   // 相对请求的基础 URI 
    'timeout'  => 2.0,  // 可以设置请求的默认超时时间 
]);

客户端在 Guzzle 中是不可变的，这意味着在创建客户端后，您无法更改客户端使用的默认值。Client 对象可以接收一个包含参数的数组：

base_uri 基础 URI

(string|UriInterface) 基 URI 用来合并到相关 URI，可以是一个字符串或者 UriInterface 的实例，当提供了相关 URL，将合并到基 URI，遵循的规则请参考 RFC 3986, section 2 章节。

// 使用 基础 URI 创建一个客户端
$client = new GuzzleHttpClient(['base_uri' => 'https://foo.com/api/']);

// 发送一个请求到 https://foo.com/api/test
$response = $client->request('GET', 'test');

// 发送一个请求到 https://foo.com/root
$response = $client->request('GET', '/root');

不想阅读 RFC 3986？这里有一些关于 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 请求的(回调)函数。 该函数被调用的时候包含 Psr7HttpMessageRequestInterface 以及参数数组，必须返回 GuzzleHttpPromisePromiseInterface ，成功时满足 Psr7HttpMessageResponseInterface 。 handler 是一个构造方法，不能在请求参数里被重写。

(混合) 构造方法中传入的其他所有参数用来当作每次请求的默认参数。

发送请求

Client 对象的方法可以很容易的发送请求：

$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：

use GuzzleHttpPsr7Request;

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

Client 对象为传输请求提供了非常灵活的处理器方式，包括请求参数、每次请求使用的中间件以及传送多个相关请求的基URI。

你可以在 Handlers and Middleware 页面找到更多关于中间件的内容。

异步请求

你可以使用 Client 提供的方法来创建异步请求：

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

// 创建要发送的 PSR-7 请求对象
$headers = ['X-Foo' => 'Bar'];
$body = 'Hello!';
$request = new Request('HEAD', 'http://httpbin.org/head', $headers, $body);

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

这些方法返回了 Promise 对象，该对象实现了由 Guzzle promises library 提供的 Promises/A+ spec ，这意味着你可以使用 then() 来调用返回值，成功使用 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();
    }
);

并发请求

你可以使用 Promise 和异步请求来同时发送多个请求：

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 函数的键来访问每个结果。
echo $results['image']->getHeader('Content-Length');
echo $results['png']->getHeader('Content-Length');

当你想发送不确定数量的请求时，可以使用 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) {
        // 每个请求成功时执行
    },
    'rejected' => function ($reason, $index) {
        // 每个请求失败时执行
    },
]);

// 开始传输并创建一个 promise
$promise = $pool->promise();

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

使用响应

前面的例子里，我们取到了 $response 变量，或者从 Promise 得到了响应，Response 对象实现了一个 PSR-7 接口PsrHttpMessageResponseInterface ，包含了很多有用的信息。

你可以获取这个响应的状态码和和原因短语 (reason phrase)：

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

你可以从响应获取头信息 (header)：

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

// 从响应中获取请求
echo $response->getHeader('Content-Length');

// 获取所有响应头
foreach ($response->getHeaders() as $name => $values) {
    echo $name . ': ' . implode(', ', $values) . "rn";
}

使用 getBody 方法可以获取响应的 Body，Body可以当成一个字符串或流对象使用：

$body = $response->getBody();

// 直接作为字符串显示 body
echo $body;

// 作为一个字符串赋值 body 给一个变量
$stringBody = (string) $body;

// 读取 body 内容的前 10 字节
$tenBytes = $body->read(10);

// 作为字符串读取剩下的 body 内容Read
$remainingBytes = $body->getContents();

查询字符串参数

你可以有多种方式来提供请求的查询字符串，你可以在请求的 URI 中设置查询字符串：

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

你可以使用 query 请求参数来声明查询字符串参数：

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

提供的数组参数将会使用 PHP 的 http_build_query ：

最后，你可以提供一个字符串作为 query 请求参数：

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

上传数据

Guzzle 为上传数据提供了一些方法。 你可以发送一个包含数据流的请求，将 body 请求参数设置成一个字符串、fopen 返回的资源、或者一个 PsrHttpMessageStreamInterface 的实例。

// 作为字符串提供 body 内容
$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() 函数创建一个 PSR-7 stream.
$body = GuzzleHttpPsr7stream_for('hello!');
$r = $client->request('POST', 'http://httpbin.org/post', ['body' => $body]);

上传 JSON 数据以及设置合适的头信息可以使用 json 请求参数这个简单的方式：

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

POST/表单请求

除了使用 body 参数来指定请求数据外，Guzzle 为发送 POST 数据提供了有用的方法。

发送表单字段

发送 application/x-www-form-urlencoded POST 请求需要你传入 form_params 数组参数，数组内指定 POST 的字段。

$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 返回的资源、或者一个

PsrHttpMessageStreamInterface 的实例。

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 选项必须设置成 GuzzleHttpCookieCookieJarInterface 的实例。

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

如果你想在所有的请求中共享 Cookies, 你可以在客户端构造器中设置 Cookies 为 true。

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

重定向

如果你没有告诉 Guzzle 不要重定向，Guzzle 会自动的进行重定向，你可以使用 allow_redirects 请求参数来自定义重定向行为。

  • 设置成 true 时将启用最大数量为5的重定向，这是默认设置。
  • 设置成 false 来禁用重定向。
  • 传入一个包含 max 键名的关联数组来声明最大重定向次数，提供可选的 strict 键名来声明是否使用严格的 RFC 标准重定向 (表示使用 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();

异常

请求传输过程中出现的错误 Guzzle 将会抛出异常。

  • 在发送网络错误(连接超时、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 异常发生在网络错误时， 该异常继承自 GuzzleHttpExceptionRequestException 。
  • 如果 http_errors 请求参数设置成 true，在 400 级别的错误的时候将会抛出 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 请求参数设置成 true，在 500 级别的错误的时候将会抛出 GuzzleHttpExceptionServerException 异常。 该异常继承自 GuzzleHttpExceptionBadResponseException 。
  • GuzzleHttpExceptionTooManyRedirectsException 异常发生在重定向次数过多时， 该异常继承自 GuzzleHttpExceptionRequestException 。

上述所有异常均继承自 GuzzleHttpExceptionTransferException 。

环境变量

Guzzle 提供了一些可自定义的环境变量：

GUZZLE_CURL_SELECT_TIMEOUT

当在 Curl 处理器时使用 curl_multi_select() 控制了 curl_multi_* 需要使用到的持续时间， 有些系统实现 PHP 的 curl_multi_select() 存在问题，调用该函数时总是等待超时的最大值。

HTTP_PROXY

定义了使用 Http 协议发送请求时使用的代理。

HTTPS_PROXY

定义了使用 Https 协议发送请求时使用的代理。

一刀（WordPress智库站长）

我们提供 WordPress主题和插件定制开发服务

本站长期承接 WordPress主题、插件、基于 WooCommerce 的商店商城开发业务。 我们有 10 年WordPress开发经验，如果你想 用WordPress开发网站, 请联系微信: iwillhappy1314，或邮箱: amos@wpcio.com 咨询。
相关文章
在WordPress主题或插件中使用Composer时避免依赖冲突
使用 JWT Authentication 验证 WordPress REST API 权限
使用 Vue.js 和 Axios 与 WordPress Rest API 交互-获取或提交WordPress数据

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

*