Guzzle HTTP 客户端请求选项详解

Guzzle HTTP 客户端请求选项详解

guzzle Guzzle, an extensible PHP HTTP client 项目地址: https://gitcode.com/gh_mirrors/gu/guzzle

概述

Guzzle 是一个功能强大的 PHP HTTP 客户端，它提供了丰富的请求选项(Request Options)来定制 HTTP 请求的各个方面。这些选项允许开发者精细控制请求行为，包括请求头、查询参数、超时设置、请求体等内容。

基础客户端配置

在使用请求选项前，我们需要先创建一个 Guzzle 客户端实例：

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

核心请求选项详解

1. 重定向控制 (allow_redirects)

作用：控制请求的重定向行为。

配置方式：

• false：禁用重定向
• true：启用重定向（默认最多5次）
• 数组：精细控制重定向行为

详细配置项：

[
    'max' => 5,             // 最大重定向次数
    'strict' => false,      // 是否使用严格RFC重定向
    'referer' => false,     // 是否添加Referer头
    'protocols' => ['http', 'https'], // 允许的重定向协议
    'track_redirects' => false // 是否跟踪重定向历史
]

示例：

$res = $client->request('GET', '/redirect/3', [
    'allow_redirects' => [
        'max' => 10,
        'strict' => true,
        'referer' => true,
        'protocols' => ['https']
    ]
]);

2. 认证设置 (auth)

作用：配置HTTP认证信息。

支持类型：

• basic：基础认证（默认）
• digest：摘要认证
• ntlm：NTLM认证

示例：

// 基础认证
$client->request('GET', '/get', ['auth' => ['username', 'password']]);

// 摘要认证
$client->request('GET', '/get', [
    'auth' => ['username', 'password', 'digest']
]);

3. 请求体设置 (body)

作用：设置请求体内容。

支持类型：

• 字符串
• fopen资源
• StreamInterface对象

示例：

// 字符串作为请求体
$client->request('PUT', '/put', ['body' => 'foo']);

// 文件流作为请求体
$resource = fopen('path/to/file', 'r');
$client->request('PUT', '/put', ['body' => $resource]);

4. 表单提交 (form_params)

作用：发送 application/x-www-form-urlencoded 类型的POST请求。

示例：

$client->request('POST', '/post', [
    'form_params' => [
        'foo' => 'bar',
        'baz' => ['hi', 'there!']
    ]
]);

5. 请求头设置 (headers)

作用：设置请求头信息。

示例：

$client->request('GET', '/get', [
    'headers' => [
        'User-Agent' => 'testing/1.0',
        'Accept' => 'application/json',
        'X-Foo' => ['Bar', 'Baz'] // 多值头
    ]
]);

6. 超时设置

连接超时 (connect_timeout)：

// 3.14秒连接超时
$client->request('GET', '/delay/5', ['connect_timeout' => 3.14]);

7. Cookie管理 (cookies)

作用：控制Cookie行为。

示例：

$jar = new \GuzzleHttp\Cookie\CookieJar();
$client->request('GET', '/get', ['cookies' => $jar]);

8. 调试模式 (debug)

作用：启用请求调试输出。

示例：

// 输出到STDOUT
$client->request('GET', '/get', ['debug' => true]);

// 输出到文件
$debugOutput = fopen('/path/to/debug.log', 'a');
$client->request('GET', '/get', ['debug' => $debugOutput]);

9. 内容编码处理 (decode_content)

作用：控制是否自动解码响应内容。

示例：

// 禁用自动解码
$client->request('GET', '/foo.js', [
    'headers' => ['Accept-Encoding' => 'gzip'],
    'decode_content' => false
]);

10. 延迟发送 (delay)

作用：设置请求发送前的延迟时间（毫秒）。

示例：

// 延迟500毫秒后发送请求
$client->request('GET', '/foo', ['delay' => 500]);

高级选项

1. 强制IP解析 (force_ip_resolve)

作用：强制使用IPv4或IPv6协议。

示例：

// 强制使用IPv4
$client->request('GET', '/foo', ['force_ip_resolve' => 'v4']);

2. TLS协议控制 (crypto_method)

作用：指定最小TLS协议版本。

示例：

// 要求至少使用TLS 1.2
$client->request('GET', '/foo', [
    'crypto_method' => STREAM_CRYPTO_METHOD_TLSv1_2_CLIENT
]);

3. 100-Continue处理 (expect)

作用：控制"Expect: 100-Continue"头行为。

配置方式：

• true：总是发送
• false：从不发送
• 数字：当请求体大于该值（字节）时发送

注意事项

1. 某些选项依赖于特定的HTTP处理器实现，特别是cURL相关的功能
2. 部分选项互斥，如body、form_params和multipart不能同时使用
3. 重定向和Cookie处理需要相应的中间件支持

通过合理组合这些请求选项，开发者可以构建出满足各种复杂场景需求的HTTP请求，实现与Web服务的高效交互。

guzzle Guzzle, an extensible PHP HTTP client 项目地址: https://gitcode.com/gh_mirrors/gu/guzzle