← All changes
|
vendor_prefixed/guzzlehttp/guzzle/src/RequestOptions.php
+111
-2
28.0
→
trunk
View file →
| @@ -4,9 +4,9 @@ | ||
| 4 | 4 | |
| 5 | 5 | /** |
| 6 | 6 | * This class contains a list of built-in Guzzle request options. |
| 7 | 7 | * |
| 8 | - * @see https://github.com/guzzle/guzzle/blob/7.12/docs/request-options.md | |
| 8 | + * @see https://github.com/guzzle/guzzle/blob/7.15/docs/request-options.md | |
| 9 | 9 | */ |
| 10 | 10 | final class RequestOptions |
| 11 | 11 | { |
| 12 | 12 | /** |
| @@ -19,9 +19,11 @@ | ||
| 19 | 19 | * |
| 20 | 20 | * - max: (int, default=5) maximum number of allowed redirects. |
| 21 | 21 | * - strict: (bool, default=false) Set to true to use strict redirects |
| 22 | 22 | * meaning redirect POST requests with POST requests vs. doing what most |
| 23 | - * browsers do which is redirect POST requests with GET requests | |
| 23 | + * browsers do which is redirect POST requests with GET requests. The | |
| 24 | + * QUERY method keeps its method and body across non-strict 301 and 302 | |
| 25 | + * redirects, and a 303 redirect is followed with a body-less GET. | |
| 24 | 26 | * - referer: (bool, default=false) Set to true to enable the Referer |
| 25 | 27 | * header. |
| 26 | 28 | * - protocols: (non-empty-array<array-key, string>, default=['http', 'https']) |
| 27 | 29 | * Allowed redirect protocols. Redirect matching is case-sensitive; use |
| @@ -88,8 +90,19 @@ | ||
| 88 | 90 | * required to use TLS 1.3. |
| 89 | 91 | */ |
| 90 | 92 | public const CRYPTO_METHOD = 'crypto_method'; |
| 91 | 93 | /** |
| 94 | + * crypto_method_max: (int) A value describing the maximum TLS protocol | |
| 95 | + * version to use. | |
| 96 | + * | |
| 97 | + * This setting must be set to one of the | |
| 98 | + * ``STREAM_CRYPTO_METHOD_TLS*_CLIENT`` constants. On the stream handler, | |
| 99 | + * PHP 7.3 or higher is required to set a maximum TLS version, and PHP 7.4 | |
| 100 | + * or higher is required to use TLS 1.3. cURL 7.54.0 or higher is required | |
| 101 | + * in order to specify a maximum TLS version with the cURL handler. | |
| 102 | + */ | |
| 103 | + public const CRYPTO_METHOD_MAX = 'crypto_method_max'; | |
| 104 | + /** | |
| 92 | 105 | * curl: (array) Raw cURL options to apply when using a built-in cURL handler. |
| 93 | 106 | */ |
| 94 | 107 | public const CURL = 'curl'; |
| 95 | 108 | /** |
| @@ -169,8 +182,94 @@ | ||
| 169 | 182 | * "headers" and "filename" cannot be used when "contents" is an array. |
| 170 | 183 | */ |
| 171 | 184 | public const MULTIPART = 'multipart'; |
| 172 | 185 | /** |
| 186 | + * multiplex: (string) Controls how a request sent through a built-in | |
| 187 | + * cURL handler relates to shared, multiplexed connections: how an HTTP/2 | |
| 188 | + * request pursues one, or, with Multiplexing::NONE, whether the transfer | |
| 189 | + * may share its connection at all. When the option is not set, | |
| 190 | + * multiplexing is left to libcurl: nothing waits, and established | |
| 191 | + * multiplex-capable connections are still shared. Use | |
| 192 | + * Multiplexing::EAGER to explicitly never wait for pending connections, | |
| 193 | + * Multiplexing::WAIT to wait on libcurl-eligible pending connections with | |
| 194 | + * CURLOPT_PIPEWAIT, normally to the same origin, | |
| 195 | + * Multiplexing::REQUIRE_EAGER to fail unless a multiplexed protocol is | |
| 196 | + * guaranteed while dialing eagerly, or Multiplexing::REQUIRE_WAIT for the | |
| 197 | + * same guarantee while also waiting on pending connections. The required | |
| 198 | + * modes require a handler that permits actual multiplexing, not merely a | |
| 199 | + * multiplexed protocol, and are rejected on a Multiplexing::NONE handler. | |
| 200 | + * The stream handler ignores EAGER and WAIT, and rejects the required | |
| 201 | + * family; CurlHandler has no multi handle to multiplex over. Explicit | |
| 202 | + * modes reject deprecated raw cURL options they conflict with: the | |
| 203 | + * required family cannot be combined with a raw CURLOPT_HTTP_VERSION, | |
| 204 | + * CURLOPT_URL, or CURLOPT_FOLLOWLOCATION; no explicit mode can be | |
| 205 | + * combined with a raw CURLOPT_PIPEWAIT on the CurlMultiHandler; and | |
| 206 | + * Multiplexing::NONE on a CurlMultiHandler that permits multiplexing | |
| 207 | + * cannot be combined with the raw CURLOPT_HTTP_VERSION, CURLOPT_HTTPAUTH | |
| 208 | + * (including the "auth" request option's "digest" and "ntlm" modes, | |
| 209 | + * which set it), CURLOPT_PROXYAUTH, CURLOPT_FOLLOWLOCATION, | |
| 210 | + * CURLOPT_HTTPHEADER, CURLOPT_ALTSVC, CURLOPT_ALTSVC_CTRL, or | |
| 211 | + * CURLOPT_PROXYTYPE cURL options. The required family also | |
| 212 | + * rejects final CURLOPT_HTTPAUTH masks that permit NTLM, which libcurl | |
| 213 | + * retries over HTTP/1.1. The required family validates its cleartext | |
| 214 | + * proxy rule against the final cURL configuration, after raw options | |
| 215 | + * such as CURLOPT_PROXY and CURLOPT_PRE_PROXY are applied; only the | |
| 216 | + * exact raw CURLOPT_NOPROXY wildcard '*' disables the primary proxy and | |
| 217 | + * pre-proxy there, and raw host-specific patterns are conservatively | |
| 218 | + * treated as leaving them active. These rejections are | |
| 219 | + * configuration-conflict checks, not remote security checks. | |
| 220 | + * | |
| 221 | + * Multiplexing::NONE disables multiplexing for a whole handler when | |
| 222 | + * passed as the "multiplex" client configuration option, which | |
| 223 | + * configures the default handler and also becomes the default request | |
| 224 | + * option, or, when constructing a handler directly, as the | |
| 225 | + * CurlMultiHandler "multiplex" constructor option. A handler | |
| 226 | + * configured with Multiplexing::NONE rejects explicitly requested wait | |
| 227 | + * modes as a configuration conflict when the transfer would actually | |
| 228 | + * wait, and always rejects the required modes, because they require a | |
| 229 | + * handler that permits actual multiplexing, not merely a multiplexed | |
| 230 | + * protocol. As a request option value, Multiplexing::NONE guarantees the | |
| 231 | + * transfer does not share its connection with any concurrent transfer. | |
| 232 | + * Multiplexing::NONE does not force HTTP/1.1: on a Multiplexing::NONE | |
| 233 | + * handler, HTTP/2 still negotiates and each transfer keeps its | |
| 234 | + * connection to itself. | |
| 235 | + * | |
| 236 | + * The request option value is accepted exactly where the guarantee | |
| 237 | + * holds and can be verified: on a CurlMultiHandler configured with | |
| 238 | + * Multiplexing::NONE, for requests whose declared protocol version is | |
| 239 | + * HTTP/1.x, on CurlHandler, and on the stream handler, which never | |
| 240 | + * multiplexes. An HTTP/2 request with a Multiplexing::NONE request | |
| 241 | + * option is rejected on a CurlMultiHandler that permits multiplexing. | |
| 242 | + * On a CurlMultiHandler that permits multiplexing, Multiplexing::NONE | |
| 243 | + * is also rejected with a custom "handle_factory", alongside a raw | |
| 244 | + * CURLMOPT_PIPELINING cURL multi option, and combined with the raw | |
| 245 | + * CURLOPT_HTTP_VERSION, CURLOPT_HTTPAUTH (including the "auth" request | |
| 246 | + * option's "digest" and "ntlm" modes, which set it), CURLOPT_PROXYAUTH, | |
| 247 | + * CURLOPT_FOLLOWLOCATION, CURLOPT_HTTPHEADER, CURLOPT_ALTSVC, | |
| 248 | + * CURLOPT_ALTSVC_CTRL, or CURLOPT_PROXYTYPE cURL options. It is also | |
| 249 | + * rejected when the request carries an Expect: 100-continue header (its | |
| 250 | + * 417 retries select connections outside the safeguards; remove an | |
| 251 | + * explicitly supplied header, or set the "expect" request option to | |
| 252 | + * false to prevent it being added automatically). | |
| 253 | + * | |
| 254 | + * On a client whose multi handler permits multiplexing, the ordinary | |
| 255 | + * non-streaming default stack - both cURL handlers available and no | |
| 256 | + * connection caps forcing multi-only routing - runs synchronous | |
| 257 | + * requests on the CurlHandler path, which satisfies the guarantee for | |
| 258 | + * any protocol version, while asynchronous requests run on the | |
| 259 | + * CurlMultiHandler, so an HTTP/2 request with Multiplexing::NONE | |
| 260 | + * succeeds synchronously and is rejected asynchronously on the same | |
| 261 | + * client. Keep-alive reuse between consecutive transfers is | |
| 262 | + * unaffected, except on libcurl versions below 7.77.0 and from 8.11.0 | |
| 263 | + * through 8.12.1, where an accepted HTTP/1.x request on a multiplexing | |
| 264 | + * CurlMultiHandler forces a fresh connection. Custom handlers receive | |
| 265 | + * the "multiplex" option unchanged: its semantics are handler-defined, | |
| 266 | + * Guzzle does not guarantee it is honored, and a client-level | |
| 267 | + * Multiplexing::NONE with a custom handler flows to it as a default | |
| 268 | + * request option without client-side enforcement. | |
| 269 | + */ | |
| 270 | + public const MULTIPLEX = 'multiplex'; | |
| 271 | + /** | |
| 173 | 272 | * on_headers: (callable) A callable that is invoked when the HTTP headers |
| 174 | 273 | * of the response have been received but the body has not yet begun to |
| 175 | 274 | * download. |
| 176 | 275 | */ |
| @@ -184,8 +283,18 @@ | ||
| 184 | 283 | * the error encountered. Included in the data is the total amount of time |
| 185 | 284 | * taken to send the request. |
| 186 | 285 | */ |
| 187 | 286 | public const ON_STATS = 'on_stats'; |
| 287 | + /** | |
| 288 | + * on_trailers: (callable) A callable that is invoked by the built-in cURL | |
| 289 | + * handlers once per successful transfer, after the response body has been | |
| 290 | + * received, with an associative array of the parsed HTTP trailers followed | |
| 291 | + * by the response. Trailer field names are lowercased and grouped | |
| 292 | + * case-insensitively; values keep their wire order. Malformed trailer | |
| 293 | + * field lines are discarded before parsing. Trailer fields are reported | |
| 294 | + * separately from response headers and are never merged into the response. | |
| 295 | + */ | |
| 296 | + public const ON_TRAILERS = 'on_trailers'; | |
| 188 | 297 | /** |
| 189 | 298 | * progress: (callable) Defines a function to invoke when transfer |
| 190 | 299 | * progress is made. The function accepts the following positional |
| 191 | 300 | * arguments: the total number of bytes expected to be downloaded, the |