请求选项

你可以通过设置Client的 请求选项 来自定义请求,请求参数控制请求的各个方面,包括头信息、查询字符串参数、超时、请求主体等。

下述所有的列子都使用下面的Client:

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

allow_redirects

摘要

描述请求的重定向行为

类型
  • bool
  • array
默认值
[
    'max'             => 5,
    'strict'          => false,
    'referer'         => true,
    'protocols'       => ['http', 'https'],
    'track_redirects' => false
]
常量

GuzzleHttp\RequestOptions::ALLOW_REDIRECTS

设置成 false 禁用重定向。

$res = $client->request('GET', '/redirect/3', ['allow_redirects' => false]);
echo $res->getStatusCode();
// 302

设置成 true (默认设置) 来启用默认最大次数为5的重定向。

$res = $client->request('GET', '/redirect/3');
echo $res->getStatusCode();
// 200

你也可以传送一个包含了以下键值对的关联数组:

  • max: (int, 默认为5) 允许重定向次数的最大值。
  • strict: (bool, 默认为false) 设置成 true 使用严格模式重定向 严格RFC模式重定向表示使用POST请求重定向POST请求 vs 大部分浏览器使用GET请求重定向POST请求。
  • referer: (bool, 默认为true) 设置成 false 重定向时禁止添加Refer头信息。
  • protocols: (array, 默认为['http', 'https']) 指定允许重定向的协议。
  • on_redirect: (callable) 发生重定向时调用PHP回调,包含了原始的请求以及接收到重定向的响应,on_redirect的任何返回将会被忽略。
  • track_redirects: (bool) 当设置成 true 时,每个重定向的URI将会按序被跟踪头信息 X-Guzzle-Redirect-History
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\UriInterface;

$onRedirect = function(
    RequestInterface $request,
    ResponseInterface $response,
    UriInterface $uri
) {
    echo 'Redirecting! ' . $request->getUri() . ' to ' . $uri . "\n";
};

$res = $client->request('GET', '/redirect/3', [
    'allow_redirects' => [
        'max'             => 10,        // allow at most 10 redirects.
        'strict'          => true,      // use "strict" RFC compliant redirects.
        'referer'         => true,      // add a Referer header
        'protocols'       => ['https'], // only allow https URLs
        'on_redirect'     => $onRedirect,
        'track_redirects' => true
    ]
]);

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

echo $res->getHeaderLine('X-Guzzle-Redirect-History');
// http://first-redirect, http://second-redirect, etc...

auth

摘要

传入HTTP认证参数的数组来使用请求,该数组索引[0]为用户名、索引[1]为密码,索引[2]为可选的内置认证类型。传入 null 进入请求认证。

类型
  • array
  • string
  • null
默认值

None

常量

GuzzleHttp\RequestOptions::AUTH

内置认证类型如下:

basic
Authorization 头信息使用 HTTP基础认证 (如果没有指定的话为默认设置)。
$client->request('GET', '/get', ['auth' => ['username', 'password']]);
digest
使用 摘要式认证 (必须被HTTP处理器支持)。
$client->request('GET', '/get', [
    'auth' => ['username', 'password', 'digest']
]);

body

摘要

body 选项用来控制一个请求(比如:PUT, POST, PATCH)的主体部分。

类型
  • string
  • fopen() resource
  • Psr\Http\Message\StreamInterface
默认值

None

常量

GuzzleHttp\RequestOptions::BODY

可以设置成下述类型:

  • string

    // You can send requests that use a string as the message body.
    $client->request('PUT', '/put', ['body' => 'foo']);
    
  • resource returned from fopen()

    // You can send requests that use a stream resource as the body.
    $resource = fopen('http://httpbin.org', 'r');
    $client->request('PUT', '/put', ['body' => $resource]);
    
  • Psr\Http\Message\StreamInterface

    // You can send requests that use a Guzzle stream object as the body
    $stream = GuzzleHttp\Psr7\stream_for('contents...');
    $client->request('POST', '/post', ['body' => $stream]);
    

cert

摘要

设置成指定PEM格式认证文件的路径的字符串,如果需要密码,需要设置成一个数组,其中PEM文件在第一个元素,密码在第二个元素。

类型
  • string
  • array
默认值

None

常量

GuzzleHttp\RequestOptions::CERT

$client->request('GET', '/', ['cert' => ['/path/server.pem', 'password']]);

cookies

摘要
声明是否在请求中使用cookie,或者要使用的cookie jar,或者要发送的cookie。
类型
GuzzleHttp\Cookie\CookieJarInterface
默认值
None
常量
GuzzleHttp\RequestOptions::COOKIES

你必须声明cookie选项为 GuzzleHttp\Cookie\CookieJarInterfacefalse

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

connect_timeout

摘要
表示等待服务器响应超时的最大值,使用 0 将无限等待 (默认行为).
类型
float
默认值
0
常量
GuzzleHttp\RequestOptions::CONNECT_TIMEOUT
// Timeout if the client fails to connect to the server in 3.14 seconds.
$client->request('GET', '/delay/5', ['connect_timeout' => 3.14]);

debug

摘要

设置成 true 或设置成一个 fopen() 返回的流来启用调试输出发送请求的处理器, 比如,当使用cURL传输请求,cURL的 CURLOPT_VERBOSE 的冗长将会发出, 当使用PHP流,流处理的提示将会发生。 如果设置为true,输出到PHP标准输出文件,如果提供了PHP流,将会输出到流。

类型
  • bool
  • fopen() resource
默认值

None

常量

GuzzleHttp\RequestOptions::DEBUG

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

执行上面的例子将会输出类似下面的结果:

* About to connect() to httpbin.org port 80 (#0)
*   Trying 107.21.213.98... * Connected to httpbin.org (107.21.213.98) port 80 (#0)
> GET /get HTTP/1.1
Host: httpbin.org
User-Agent: Guzzle/4.0 curl/7.21.4 PHP/5.5.7

< HTTP/1.1 200 OK
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Date: Sun, 16 Feb 2014 06:50:09 GMT
< Server: gunicorn/0.17.4
< Content-Length: 335
< Connection: keep-alive
<
* Connection #0 to host httpbin.org left intact

decode_content

摘要

声明是否自动解码 Content-Encoding 响应 (gzip, deflate等) 。

类型
  • string
  • bool
默认值

true

常量

GuzzleHttp\RequestOptions::DECODE_CONTENT

该选项可以用来控制Content-Encoding如何响应主体的,默认 decode_content 设置为 true,表示Guzzle将自动解码gzip,deflate等响应。

当设置成 false ,响应的主体将不会被解码,意味着字节将毫无变化的通过处理器。

// Request gzipped data, but do not decode it while downloading
$client->request('GET', '/foo.js', [
    'headers'        => ['Accept-Encoding' => 'gzip'],
    'decode_content' => false
]);

当设置成字符串,响应的字节将被解码,提供 decode_content 选项的字符串将作为请求的 Accept-Encoding 报文头。

// Pass "gzip" as the Accept-Encoding header.
$client->request('GET', '/foo.js', ['decode_content' => 'gzip']);

delay

摘要

发送请求前延迟的毫秒数值

类型
  • integer
  • float
默认值

null

常量

GuzzleHttp\RequestOptions::DELAY

expect

摘要

控制"Expect: 100-Continue"报文头的行为。

类型
  • bool
  • integer
默认值

1048576

常量

GuzzleHttp\RequestOptions::EXPECT

设置成 true 来为所有发送主体的请求启用 "Expect: 100-Continue" 报文头; 设置成 false 来为所有的请求禁用 "Expect: 100-Continue" 报文头; 设置成一个数值,有效载荷的大小必须大于预计发送的值,设置成数值将会为所有不确定有效载荷大小或主体不能确定指针位置的请求发送Expect报文头,

默认情况下,当请求的主体大于1MB以及请求使用的HTTP/1.1,Guzzle将会添加 "Expect: 100-Continue" 报文头。

form_params

摘要
用来发送一个 application/x-www-form-urlencoded POST请求.
类型
array
常量
GuzzleHttp\RequestOptions::FORM_PARAMS

关联数组由表单字段键值对构成,每个字段值可以是一个字符串或一个包含字符串元素的数组。 当没有准备 "Content-Type" 报文头的时候,将设置为 "application/x-www-form-urlencoded"。

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

headers

摘要
要添加到请求的报文头的关联数组,每个键名是header的名称,每个键值是一个字符串或包含代表头字段字符串的数组。
类型
array
Defaults
None
常量
GuzzleHttp\RequestOptions::HEADERS
// Set various headers on a request
$client->request('GET', '/get', [
    'headers' => [
        'User-Agent' => 'testing/1.0',
        'Accept'     => 'application/json',
        'X-Foo'      => ['Bar', 'Baz']
    ]
]);

创建Client的时候头信息可以作为默认选项添加,当头信息使用默认选项时,它们只能在请求没有包含特殊头信息的时候生效, 这包括了Client的 send()sendAsync() 方法,以及Client创建的请求(比如 request()requestAsync())。

$client = new GuzzleHttp\Client(['headers' => ['X-Foo' => 'Bar']]);

// Will send a request with the X-Foo header.
$client->request('GET', '/get');

// Sets the X-Foo header to "test", which prevents the default header
// from being applied.
$client->request('GET', '/get', ['headers' => ['X-Foo' => 'test']);

// Will disable adding in default headers.
$client->request('GET', '/get', ['headers' => null]);

// Will not overwrite the X-Foo header because it is in the message.
use GuzzleHttp\Psr7\Request;
$request = new Request('GET', 'http://foo.com', ['X-Foo' => 'test']);
$client->send($request);

// Will overwrite the X-Foo header with the request option provided in the
// send method.
use GuzzleHttp\Psr7\Request;
$request = new Request('GET', 'http://foo.com', ['X-Foo' => 'test']);
$client->send($request, ['headers' => ['X-Foo' => 'overwrite']]);

http_errors

摘要
设置成 false 来禁用HTTP协议抛出的异常(如 4xx 和 5xx 响应),默认情况下HTPP协议出错时会抛出异常。
类型
bool
默认值
true
常量
GuzzleHttp\RequestOptions::HTTP_ERRORS
$client->request('GET', '/status/500');
// Throws a GuzzleHttp\Exception\ServerException

$res = $client->request('GET', '/status/500', ['http_errors' => false]);
echo $res->getStatusCode();
// 500

json

摘要
json 选项用来轻松将JSON数据当成主体上传, 如果没有设置Content-Type头信息的时候会设置成 application/json
类型
能够 json_encode() 操作的PHP类型。
默认值
None
常量
GuzzleHttp\RequestOptions::JSON
$response = $client->request('PUT', '/put', ['json' => ['foo' => 'bar']]);

这里的例子使用了 tap 中间件用来查看发送了什么请求。

use GuzzleHttp\Middleware;

// Grab the client's handler instance.
$clientHandler = $client->getConfig('handler');
// Create a middleware that echoes parts of the request.
$tapMiddleware = Middleware::tap(function ($request) {
    echo $request->getHeader('Content-Type');
    // application/json
    echo $request->getBody();
    // {"foo":"bar"}
});

$response = $client->request('PUT', '/put', [
    'json'    => ['foo' => 'bar'],
    'handler' => $tapMiddleware($clientHandler)
]);

multipart

摘要
设置请求的主体为 multipart/form-data 表单。
类型
array
常量
GuzzleHttp\RequestOptions::MULTIPART

multipart 的值是一个关联数组,每个元素包含以下键值对:

  • name: (string, required) 表单字段名称
  • contents: (StreamInterface/resource/string, required) 表单元素中要使用的数据
  • headers: (array) 可选的表单元素要使用的键值对数组
  • filename: (string) 可选的作为要发送的文件名称
$client->request('POST', '/post', [
    'multipart' => [
        [
            'name'     => 'foo',
            'contents' => 'data',
            'headers'  => ['X-Baz' => 'bar']
        ],
        [
            'name'     => 'baz',
            'contents' => fopen('/path/to/file', 'r')
        ],
        [
            'name'     => 'qux',
            'contents' => fopen('/path/to/file', 'r'),
            'filename' => 'custom_filename.txt'
        ],
    ]
]);

on_headers

摘要

回调函数,当响应的HTTP头信息被接收且主体部分还未开始下载的时候调用。

类型
  • callable
常量

GuzzleHttp\RequestOptions::ON_HEADERS

该回调接收 Psr\Http\ResponseInterface 对象。 如果该回调抛出异常,与响应相关的Promise将会接收到 GuzzleHttp\Exception\RequestException 抛出的异常。

在数据写入下游之前,你应该需要知道接收到的头信息与状态码。

// Reject responses that are greater than 1024 bytes.
$client->request('GET', 'http://httpbin.org/stream/1024', [
    'on_headers' => function (ResponseInterface $response) {
        if ($response->getHeaderLine('Content-Length') > 1024) {
            throw new \Exception('The file is too big!');
        }
    }
]);

on_stats

摘要

on_stats 允许你获取请求传输数据统计以及处理器在底层传输的详情. on_stats 是个回调,当处理器完成传输一个请求的时候被调用。 该回调被调用请求传输数据统计、接收到响应,或遇到错误,包含发送请求数据时间的总量。

类型
  • callable
常量

GuzzleHttp\RequestOptions::ON_STATS

该回调接收 GuzzleHttp\TransferStats 对象。

use GuzzleHttp\TransferStats;

$client = new GuzzleHttp\Client();

$client->request('GET', 'http://httpbin.org/stream/1024', [
    'on_stats' => function (TransferStats $stats) {
        echo $stats->getEffectiveUri() . "\n";
        echo $stats->getTransferTime() . "\n";
        var_dump($stats->getHandlerStats());

        // You must check if a response was received before using the
        // response object.
        if ($stats->hasResponse()) {
            echo $stats->getResponse()->getStatusCode();
        } else {
            // Error data is handler specific. You will need to know what
            // type of error data your handler uses before using this
            // value.
            var_dump($stats->getHandlerErrorData());
        }
    }
]);

proxy

摘要

传入字符串来指定HTTP代理,或者为不同代理指定不同协议的数组。

类型
  • string
  • array
默认值

None

常量

GuzzleHttp\RequestOptions::PROXY

传入字符串为所有协议指定一个代理:

$client->request('GET', '/', ['proxy' => 'tcp://localhost:8125']);

传入关联数组来为特殊的URI Scheme指定特色的HTTP代理(比如"http", "https") 提供一个 no 键值对来提供一组不需要使用代理的主机名。

$client->request('GET', '/', [
    'proxy' => [
        'http'  => 'tcp://localhost:8125', // Use this proxy with "http"
        'https' => 'tcp://localhost:9124', // Use this proxy with "https",
        'no' => ['.mit.edu', 'foo.com']    // Don't use a proxy with these
    ]
]);

query

摘要

要添加到请求的查询字符串的关联数组或查询字符串。

类型
  • array
  • string
默认值

None

常量

GuzzleHttp\RequestOptions::QUERY

// Send a GET request to /get?foo=bar
$client->request('GET', '/get', ['query' => ['foo' => 'bar']]);

query 选项查询字符串指定,将会覆盖在请求时提供的查询字符串值。

// Send a GET request to /get?foo=bar
$client->request('GET', '/get?abc=123', ['query' => ['foo' => 'bar']]);

sink

摘要

声明响应的主体部分将要保存的位置。

类型
  • string (path to file on disk)
  • fopen() resource
  • Psr\Http\Message\StreamInterface
默认值

PHP temp stream

常量

GuzzleHttp\RequestOptions::SINK

传入字符串来指定将要保存响应主体内容的文件的路径:

$client->request('GET', '/stream/20', ['sink' => '/path/to/file']);

传入 fopen() 返回的资源将响应写入PHP流:

$resource = fopen('/path/to/file', 'w');
$client->request('GET', '/stream/20', ['sink' => $resource]);

传入 Psr\Http\Message\StreamInterface 对象将响应写入打开的PSR-7流。

$resource = fopen('/path/to/file', 'w');
$stream = GuzzleHttp\Psr7\stream_for($resource);
$client->request('GET', '/stream/20', ['save_to' => $stream]);

ssl_key

摘要

指定一个链接到私有SSL密钥的PEM格式的文件的路径的字符串。 如果需要密码,设置成一个数组,数组第一个元素为链接到私有SSL密钥的PEM格式的文件的路径,第二个元素为认证密码。

类型
  • string
  • array
默认值

None

常量

GuzzleHttp\RequestOptions::SSL_KEY

stream

摘要
设置成 true 流响应,而非下载响应。
类型
bool
默认值
false
常量
GuzzleHttp\RequestOptions::STREAM
$response = $client->request('GET', '/stream/20', ['stream' => true]);
// Read bytes off of the stream until the end of the stream is reached
$body = $response->getBody();
while (!$body->eof()) {
    echo $body->read(1024);
}

synchronous

摘要
设置成 true 来通知HTTP处理器你要等待响应,这有利于优化。
类型
bool
默认值
none
常量
GuzzleHttp\RequestOptions::SYNCHRONOUS

verify

摘要

请求时验证SSL证书行为。

  • 设置成 true 启用SSL证书验证,默认使用操作系统提供的CA包。
  • 设置成 false 禁用证书验证(这是不安全的!)。
  • 设置成字符串启用验证,并使用该字符串作为自定义证书CA包的路径。
类型
  • bool
  • string
默认值

true

常量

GuzzleHttp\RequestOptions::VERIFY

// Use the system's CA bundle (this is 默认设置)
$client->request('GET', '/', ['verify' => true]);

// Use a custom SSL certificate on disk.
$client->request('GET', '/', ['verify' => '/path/to/cert.pem']);

// Disable validation entirely (don't do this!).
$client->request('GET', '/', ['verify' => false]);

并非所有的系统磁盘上都存在CA包,比如,Windows和OS X并没有通用的本地CA包。 当设置"verify" 为 true 时,Guzzle将尽力在你的操作系统中找到合适的CA包, 当使用cURL或PHP 5.6以上版本的流时,Guzzle将按以下顺序尝试查找CA包:

  1. 检查php.ini文件中是否设置了 openssl.cafile
  2. 检查php.ini文件中是否设置了 curl.cainfo
  3. 检查 /etc/pki/tls/certs/ca-bundle.crt 是否存在 (Red Hat, CentOS, Fedora; 由ca-certificates包提供)
  4. 检查 /etc/ssl/certs/ca-certificates.crt 是否存在 (Ubuntu, Debian; 由ca-certificates包提供)
  5. 检查 /usr/local/share/certs/ca-root-nss.crt 是否存在 (FreeBSD; 由ca_root_nss包提供)
  6. 检查 /usr/local/etc/openssl/cert.pem 是否存在 (OS X; 由homebrew提供)
  7. 检查 C:\windows\system32\curl-ca-bundle.crt 是否存在 (Windows)
  8. 检查 C:\windows\curl-ca-bundle.crt 是否存在 (Windows)

查询的结果将缓存在内存中,以便同一进程后续快速调用。 然而在有些服务器如Apache中每个请求都在独立的进程中,你应该考虑设置 openssl.cafile 环境变量,指定到磁盘文件,以便整个过程都跳过。

如果你不需要特殊的证书包,可以使用Mozilla提供的通用CA包,你可以在 这里 下载(由cURL的维护者提供)。 一旦磁盘有了CA包,你可以设置PHP ini配置文件,指定该文件的路径到变量 openssl.cafile 中,这样就可以在请求中省略 "verify" 参数。 你可以在 cURL 网站 发现更多关于SSL证书的细节。

timeout

摘要
请求超时的秒数。使用 0 无限期的等待(默认行为)。
类型
float
默认值
0
常量
GuzzleHttp\RequestOptions::TIMEOUT
// Timeout if a server does not return a response in 3.14 seconds.
$client->request('GET', '/delay/5', ['timeout' => 3.14]);
// PHP Fatal error:  Uncaught exception 'GuzzleHttp\Exception\RequestException'

version

摘要
请求要使用到的协议版本。
类型
string, float
默认值
1.1
常量
GuzzleHttp\RequestOptions::VERSION
// Force HTTP/1.0
$request = $client->request('GET', '/get', ['version' => 1.0]);