你可以通过以下方式定制由客户端创建和传输的请求 请求选项。请求选项可以控制一个请求的各个方面 包括头文件、查询字符串参数、超时设置、请求的正文等等。 请求的主体,以及更多。
以下所有的例子都使用了以下的客户端。
$client = new GuzzleHttp\Client(['base_uri' => 'http://httpbin.org']);
描述了一个请求的重定向行为
。[
'max' => 5,
'strict' => false,
'referer' => false,
'protocols' => ['http', 'https'],
'track_redirects' => false
]
GuzzleHttpRequestOptions::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, default=5) 允许重定向的最大数量。
严格。(bool, default=false) 设置为 "true "以使用严格的重定向。 严格的RFC兼容的重定向意味着POST重定向请求被作为 POST请求,而不是像大多数浏览器那样将POST请求与GET请求重定向。
referer: (bool, default=false) 设置为 "true",以便在重定向时能够添加Refer 头。
protocols: (array, default=['http', 'https']) 指定哪些协议是
指定哪些协议被允许用于重定向请求。on_redirect: (callable)当遇到重定向时调用的PHP可调用程序。 时被调用。该可调用程序被调用时,会包含原始请求和收到的 收到的重定向响应。任何来自on_redirect的返回值 函数的任何返回值都被忽略。
track_redirects: (bool)当设置为true
时,每个重定向的URI和遇到的状态
代码将被追踪到X-Guzzle-Redirect-History
和
X-Guzzle-Redirect-Status-History
头信息中分别跟踪。所有的URI和
注意:当追踪重定向时,X-Guzzle-Redirect-History
头信息将
不包括初始请求的URI和X-Guzzle-Redirect-Status-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...
echo $res->getHeaderLine('X-Guzzle-Redirect-Status-History');
// 301, 302, etc...
警告
这个选项只有在你的处理程序有以下内容时才有效果
GuzzleHttp\Middleware::redirect
中间件时,这个选项才会生效。这个中间件被添加到
当创建一个没有处理程序的客户端时,这个中间件被默认添加。
当用GuzzleHttp\HandlerStack::create
创建一个处理程序时,默认会添加这个中间件。
注意事项
当使用GuzzleHttp/Client::sendRequest()
进行请求时,这个选项没有效果。为了与PSR-18保持一致,任何重定向响应都会按原样返回。
传入一个HTTP认证参数的数组,以便在请求中使用。
请求一起使用。该数组必须包含索引为[0]的用户名,索引为
索引[1],你还可以选择提供一个内置的认证类型在
index [2]. 通过null
来禁用一个请求的认证
无
GuzzleHttpRequestOptions::AUTH
内置的认证类型如下。
Authorization
头中(如果没有指定,则使用默认设置)。
指定时使用的默认设置)。$client->request('GET', '/get', ['auth' => ['username', 'password']]);
$client->request('GET', '/get', [
'auth' => ['username', 'password', 'digest']
]);
注意事项
目前,只有在使用cURL处理程序时才支持这个功能。 计划创建一个可以用于任何HTTP处理程序的替代方案。 计划。
$client->request('GET', '/get', [
'auth' => ['username', 'password', 'ntlm']
]);
注意事项
目前只在使用cURL处理程序时支持这个功能。
body
选项是用来控制实体请求的主体的
包围的请求(例如,PUT、POST、PATCH)。
fopen()
资源Psr\Http\MessageStreamInterface
无
GuzzleHttpRequestOptions::BODY
该设置可被设置为以下任何一种类型。
string
//你可以发送使用字符串作为信息主体的请求。
$client->request('PUT', '/put', ['body' => 'foo'])。
从fopen()
//你可以发送使用流资源作为主体的请求。
$resource = \GuzzleHttp\Psr7\Utils::tryFopen('http://httpbin.org', 'r')。
$client->request('PUT', '/put', ['body' => $resource])。
Psr\HttpMessage\StreamInterface
//你可以发送使用Guzzle流对象作为主体的请求。
$stream = GuzzleHttp\Psr7\Utils::streamFor('contents...')。
$client->request('POST', '/post', ['body' => $stream])。
注意事项
此选项不能与form_params
、multipart
,或json
一起使用。
设置为一个字符串,以指定包含PEM格式的客户端证书的文件路径。 格式的客户端证书。如果需要密码,则设置为 一个数组,在第一个数组元素中包含PEM文件的路径 后面是第二个数组中的证书所需的密码。 元素。
无
GuzzleHttpRequestOptions::CERT
$client->request('GET', '/', ['cert' => ['/path/server.pem', 'password']]);
GuzzleHttp\Cookie/CookieJarInterface
GuzzleHttp\RequestOptions::COOKIES
你必须将cookies选项指定为GuzzleHttp\Cookie/CookieJarInterface
或false
。
$jar = new \GuzzleHttp\Cookie\CookieJar();
$client->request('GET', '/get', ['cookies' => $jar]);
警告
这个选项只有在你的处理程序有以下内容时才会产生作用
GuzzleHttp\Middleware::cookies
中间件。这个中间件被添加到
当创建一个没有处理程序的客户端时,这个中间件被默认添加。
当用GuzzleHttp\default_handler
创建一个处理程序时,这个中间件被默认添加。
技巧
当创建一个客户端时,你可以将默认的cookie选项设置为true
来使用一个与客户端相关的共享cookie会话。
0
来无限期地等待(默认行为)。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]);
注意事项
这个设置必须被用于发送请求的HTTP处理器所支持。
connect_timeout
目前只被内置的cURL
处理程序支持。
设置为true
或设置为由fopen()
返回的PHP流,以便
启用用于发送请求的处理程序的调试输出。比如说。
当使用cURL传输请求时,cURL的verboseCURLOPT_VERBOSE
将被排放出来。当使用PHP流包装器时,流包装器的
通知将被发射出来。如果设置为true,输出将被写入
PHP的STDOUT。如果提供了一个PHP流,输出将被写入该流中
fopen()
资源无
GuzzleHttpRequestOptions::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
指定是否Content-Encoding
响应(gzip,
deflate等)自动解码。
true
GuzzleHttpRequestOptions::DECODE_CONTENT
这个选项可以用来控制如何处理内容编码的响应体。
处理。默认情况下,decode_content
被设置为true,意味着任何gzipped
或deflated响应都会被Guzzle解码。
当设置为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']);
控制 "Expect: 100-Continue "标题的行为
。1048576
GuzzleHttpRequestOptions::EXPECT
设置为true
以启用 "Expect: 100-Continue "标头,用于所有发送正文的请求。
发送一个正文。设置为false
以禁用所有请求的 "Expect: 100-Continue"
头的功能。设置为一个数字,这样有效载荷的大小必须大于
大于该数字才能发送Expect头。设置为一个
数字将为所有无法确定有效载荷大小的请求发送 "期望 "标头。
的所有请求发送Expect头,这些请求的有效载荷大小无法确定,或者请求的正文不能倒退。
默认情况下,当一个请求的主体大小超过1MB,并且请求使用的是HTTP/1.1时,Guzzle会添加 "Expect: 100-Continue "头。
注意事项
这个选项只在使用HTTP/1.1时生效。HTTP/1.0和 HTTP/2.0协议不支持 "Expect: 100-Continue "标头。 对处理 "Expect: 100-Continue "工作流的支持必须由Guzzle的HTTP处理程序实现。 支持处理 "Expect: 100-Continue "工作流程必须由客户端使用的Guzzle HTTP处理程序来实现。
GuzzleHttp\RequestOptions::FORCE_IP_RESOLVE
// Force ipv4 protocol
$client->request('GET', '/foo', ['force_ip_resolve' => 'v4']);
// Force ipv6 protocol
$client->request('GET', '/foo', ['force_ip_resolve' => 'v6']);
注意事项
这个设置必须被用于发送请求的HTTP处理器所支持。
force_ip_resolve
目前只被内置的cURL
和流处理程序支持。
GuzzleHttp\RequestOptions::FORM_PARAMS
表单字段名与值的关联数组,每个值是一个字符串或字符串数组。 字符串的数组。设置内容类型头为 当没有Content-Type头时,将Content-Type头设置为application/x-www-form-urlencoded。 存在。
$client->request('POST', '/post', [
'form_params' => [
'foo' => 'bar',
'baz' => ['hi', 'there!']
]
]);
注意事项
form_params
不能与multipart
选项一起使用。你将需要使用
一个或另一个。对于form_params
,使用application/x-www-form-urlencoded
请求,以及multipart
用于multipart/form-data
请求。
此选项不能用于body
、multipart
,或json
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']
]
]);
在创建客户端时,可以将头文件作为默认选项添加。当头文件
被用作默认选项时,它们只在被创建的请求
不包含特定的头信息。这包括在中传递给客户端的请求
和
send()
方法中传递给客户端的请求,以及由客户端创建的请求
由客户端创建的请求(例如,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']]);
false
以禁止在HTTP协议中抛出异常。
错误(例如,4xx和5xx响应)。默认情况下,当遇到以下情况时,会抛出异常
遇到HTTP协议错误时抛出异常。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
警告
这个选项只有在你的处理程序有以下内容时才会产生作用
GuzzleHttp\Middleware::httpErrors
中间件时,这个选项才会生效。这个中间件被添加到
当创建一个没有处理程序的客户端时,这个中间件被默认添加。
当用GuzzleHttp\default_handler
创建一个处理程序时,这个中间件被默认加入。
国际化域名(IDN)支持(默认启用,如果
intl
扩展是可用的)。
true
如果intl
扩展可用(且ICU库为4.6+,适用于PHP 7.2+),false
否则
GuzzleHttpRequestOptions::IDN_CONVERSION
$client->request('GET', 'https://яндекс.рф');
// яндекс.рф is translated to xn--d1acpjx3f.xn--p1ai before passing it to the handler
$res = $client->request('GET', 'https://яндекс.рф', ['idn_conversion' => false]);
// The domain part (яндекс.рф) stays unmodified
启用/禁用IDN支持,也可以通过结合以下方式进行精确控制
IDNA_*常量(IDNA_ERROR_*除外),见$options
参数中的
idn_to_ascii()
文档中的更多细节。
json
选项被用来轻松上传JSON编码的数据作为
请求的主体。如果没有Content-Type头,则会添加application/json
的Content-Type头。
如果消息中没有Content-Type头,就会被添加。json_encode()
函数所操作的PHP类型。GuzzleHttp\RequestOptions::JSON
$response = $client->request('PUT', '/put', ['json' => ['foo' => 'bar']]);
下面是一个使用tap
中间件的例子,看看电线上发送的请求是什么。
use GuzzleHttp\Middleware;
// Create a middleware that echoes parts of the request.
$tapMiddleware = Middleware::tap(function ($request) {
echo $request->getHeaderLine('Content-Type');
// application/json
echo $request->getBody();
// {"foo":"bar"}
});
// The $handler variable is the handler passed in the
// options to the client constructor.
$response = $client->request('PUT', '/put', [
'json' => ['foo' => 'bar'],
'handler' => $tapMiddleware($handler)
]);
注意事项
这个请求选项不支持自定义Content-Type头
或PHP的json_encode() 的任何选项。
函数。如果你需要定制这些设置,那么你必须将
JSON编码的数据,并使用body
request选项将其传递到请求中。
选项,并且你必须使用
headers
请求选项来指定正确的内容类型头。
此选项不能与body
、form_params
,或multipart
一起使用。
GuzzleHttp\RequestOptions::MULTIPART
multipart
的值是一个关联数组,每个数组包含以下键值对。
name
: (string, required) 表单字段名称内容
。(StreamInterface/resource/string, required) 要在表单元素中使用的数据。
表格元素中使用的数据。headers
: (数组) 可选的自定义标题的关联数组,以用于
表单元素一起使用。文件名
。(string) 可选的字符串,作为部分的文件名发送。use GuzzleHttp\Psr7;
$client->request('POST', '/post', [
'multipart' => [
[
'name' => 'foo',
'contents' => 'data',
'headers' => ['X-Baz' => 'bar']
],
[
'name' => 'baz',
'contents' => Psr7\Utils::tryFopen('/path/to/file', 'r')
],
[
'name' => 'qux',
'contents' => Psr7\Utils::tryFopen('/path/to/file', 'r'),
'filename' => 'custom_filename.txt'
],
]
]);
注意事项
multipart
不能与form_params
选项一起使用。你将需要
使用一个或另一个。对于form_params
,使用application/x-www-form-urlencoded
请求,以及multipart
用于multipart/form-data
请求。
此选项不能与body
、form_params
,或json
一同使用。
当响应的HTTP头信息已经收到,但主体还没有开始下载时,会调用一个可调用程序。 但是正文还没有开始下载。
GuzzleHttpRequestOptions::ON_HEADERS
这个可调用对象接受一个Psr\HttpMessage\ResponseInterface
对象。如果一个异常
被调用的对象抛出,那么与响应相关的承诺将被拒绝。
会被拒绝,并附带一个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!');
}
}
]);
注意事项
当编写HTTP处理程序时,on_headers
函数必须被调用
在将数据写入响应的主体之前,必须调用该函数。
on_stats
允许你访问一个请求的传输统计数据,并访问处理程序的下层传输细节。
请求的传输统计数据,并访问与你的客户相关联的处理程序的较低级别的传输细节。
与你的客户端相关联的处理程序的低级传输细节。on_stats
是一个可调用的函数,在处理程序完成发送请求时被调用。
当处理程序发送完一个请求时被调用。该回调被调用
调用,并提供关于请求、收到的响应或遇到的错误的传输统计数据。
遇到的错误。数据中包括发送请求所花费的总时间
GuzzleHttpRequestOptions::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());
}
}
]);
定义了一个函数,当转移进展时调用
。无
GuzzleHttpRequestOptions::PROGRESS
该函数接受以下位置参数。
// Send a GET request to /get?foo=bar
$result = $client->request(
'GET',
'/',
[
'progress' => function(
$downloadTotal,
$downloadedBytes,
$uploadTotal,
$uploadedBytes
) {
//do something
},
]
);
传递一个字符串来指定一个HTTP代理,或者传递一个数组来指定不同协议的不同代理。 不同协议的不同代理。
无
GuzzleHttpRequestOptions::PROXY
传递一个字符串来指定所有协议的代理。
$client->request('GET', '/', ['proxy' => 'http://localhost:8125']);
传递一个关联数组来指定特定URI方案的HTTP代理
(即 "http"、"https")。提供一个no
键值对,以提供一个不应被代理的主机名列表。
不应被代理的主机名的列表。
注意事项
Guzzle会用你的环境变量自动填充这个值
NO_PROXY
环境变量。然而,当提供一个代理
请求选项时,由你来提供从no
解析出来的值。
NO_PROXY
环境变量中解析出的值。
(例如,explode(',', getenv('NO_PROXY'))
)。
$client->request('GET', '/', [
'proxy' => [
'http' => 'http://localhost:8125', // Use this proxy with "http"
'https' => 'http://localhost:9124', // Use this proxy with "https",
'no' => ['.mit.edu', 'foo.com'] // Don't use a proxy with these
]
]);
注意事项
你可以提供包含方案、用户名和密码的代理URL。
例如,"http://username:[email protected]:10"
。
查询字符串值的关联数组或查询字符串添加到请求中。
无
GuzzleHttpRequestOptions::QUERY
// Send a GET request to /get?foo=bar
$client->request('GET', '/get', ['query' => ['foo' => 'bar']]);
在query
选项中指定的查询字符串将覆盖在一个请求的URI中提供的所有查询字符串值。
// Send a GET request to /get?foo=bar
$client->request('GET', '/get?abc=123', ['query' => ['foo' => 'bar']]);
default_socket_timeout
PHP ini 设置的值。GuzzleHttp\RequestOptions::READ_TIMEOUT
该超时适用于流式主体上的单个读取操作(当stream
选项被启用时)。
$response = $client->request('GET', '/stream', [
'stream' => true,
'read_timeout' => 10,
]);
$body = $response->getBody();
// Returns false on timeout
$data = $body->read(1024);
// Returns false on timeout
$line = fgets($body->detach());
指定响应的主体将被保存在哪里。
fopen()
资源Psr\Http\MessageStreamInterface
PHP temp stream
GuzzleHttpRequestOptions::SINK
传递一个字符串,指定一个文件的路径,该文件将存储响应体的内容。
$client->request('GET', '/stream/20', ['sink' => '/path/to/file']);
传递一个从fopen()
返回的资源,将响应写入一个PHP流。
$resource = \GuzzleHttp\Psr7\Utils::tryFopen('/path/to/file', 'w');
$client->request('GET', '/stream/20', ['sink' => $resource]);
传递一个Psr\Http\MessageStreamInterface
对象,将响应体流到一个开放的PSR-7流。
$resource = \GuzzleHttp\Psr7\Utils::tryFopen('/path/to/file', 'w');
$stream = \GuzzleHttp\Psr7\Utils::streamFor($resource);
$client->request('GET', '/stream/20', ['save_to' => $stream]);
注意事项
save_to
请求选项已被弃用,改用
sink
请求选项已被废弃。提供save_to
选项现在是的别名
sink
。
指定一个包含PEM格式的私人SSL密钥的文件路径。 格式的私人SSL密钥的文件路径。如果需要密码,则设置为一个数组,在第一个数组元素中包含SSL密钥的路径,然后是需要的密码。 在第一个数组元素中包含SSL密钥的路径,在第二个元素中包含证书所需的密码。
。无
GuzzleHttpRequestOptions::SSL_KEY
注意事项
ssl_key
是由HTTP处理程序实现的。目前只有
支持,但也可能被其他第三方的
处理程序支持。
true
以流式传输响应,而不是预先下载所有内容。
而不是提前下载。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);
}
注意事项
流式响应支持必须由客户端使用的HTTP处理程序实现。 客户端使用的HTTP处理程序实现。这个选项可能不是每个HTTP处理程序都支持的,但是 响应对象的接口仍然是相同的,不管处理程序是否支持它。 响应对象的接口都是一样的,不管处理程序是否支持它。
GuzzleHttp\RequestOptions::SYNCHRONOUS
描述了一个请求的SSL证书验证行为
。true
以启用SSL证书验证并使用操作系统提供的默认
false
以禁用证书验证(这是不安全的!)。
true
GuzzleHttpRequestOptions::VERIFY
// Use the system's CA bundle (this is the default setting)
$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]);
如果你不需要特定的证书束,那么Mozilla提供了一个常用的CA束。 常用的CA捆绑,可以下载 这里 (由cURL的维护者提供)。一旦你在磁盘上有了一个CA捆绑包 一旦你在磁盘上有一个CA包,你可以设置 "openssl.cafile "PHP ini的设置,以指向文件的路径。 文件的路径,这样就可以省略 "验证 "请求选项。更多关于 更多关于SSL证书的细节可以在以下网站上找到 cURL网站。