wordpress-seo / vendor_prefixed / guzzlehttp / guzzle / src / RequestOptions.php

RequestOptions.php in Yoast SEO – Advanced SEO with real-time guidance and built-in AI 28.5, at vendor_prefixed/guzzlehttp/guzzle/src/RequestOptions.php

396 lines 19.7 KB

Raw Download Zip

1	<?php
2
3	namespace YoastSEO_Vendor\GuzzleHttp;
4
5	/**
6	* This class contains a list of built-in Guzzle request options.
7	*
8	* @see https://github.com/guzzle/guzzle/blob/7.15/docs/request-options.md
9	*/
10	final class RequestOptions
11	{
12	/**
13	* allow_redirects: (bool\|array) Controls redirect behavior. Pass false
14	* to disable redirects, pass true to enable redirects, pass an
15	* associative to provide custom redirect settings. Defaults to "false".
16	* This option only works if your handler has the RedirectMiddleware. When
17	* passing an associative array, you can provide the following key value
18	* pairs:
19	*
20	* - max: (int, default=5) maximum number of allowed redirects.
21	* - strict: (bool, default=false) Set to true to use strict redirects
22	* meaning redirect POST requests with POST requests vs. doing what most
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.
26	* - referer: (bool, default=false) Set to true to enable the Referer
27	* header.
28	* - protocols: (non-empty-array<array-key, string>, default=['http', 'https'])
29	* Allowed redirect protocols. Redirect matching is case-sensitive; use
30	* "http" and "https".
31	* - on_redirect: (callable) PHP callable that is invoked when a redirect
32	* is encountered. The callable is invoked with the request, the redirect
33	* response that was received, and the effective URI. Any return value
34	* from the on_redirect function is ignored.
35	* - track_redirects: (bool, default=false) Track redirected URI and status
36	* history in response headers.
37	*/
38	public const ALLOW_REDIRECTS = 'allow_redirects';
39	/**
40	* auth: (array{0: string, 1: string, 2?: string\|null}\|string\|false\|null)
41	* Pass an array of HTTP authentication parameters to use with the request.
42	* The array must contain the username in index [0], the password in index
43	* [1], and you can optionally provide a built-in authentication type in
44	* index [2]. Pass false or null to disable authentication for a request.
45	* String values are passed through for custom handlers.
46	*/
47	public const AUTH = 'auth';
48	/**
49	* body: (resource\|string\|null\|int\|float\|bool\|\Psr\Http\Message\StreamInterface\|(callable&object)\|\Iterator\|\Stringable)
50	* Body to send in the request. Callable arrays are arrays, and arrays are
51	* not valid body values in Guzzle.
52	*/
53	public const BODY = 'body';
54	/**
55	* cert: (string\|array{0: string, 1?: string\|null}) Set to a string to
56	* specify the path to a client certificate file. PEM is the default
57	* certificate format. If a password is required, set cert to an array
58	* containing the certificate path in the first array element followed by
59	* the certificate password in the second array element. A null password is
60	* treated the same as omitting it. Use cert_type to specify another
61	* supported certificate format.
62	*/
63	public const CERT = 'cert';
64	/**
65	* cert_type: (string) Specify the SSL client certificate file type.
66	*/
67	public const CERT_TYPE = 'cert_type';
68	/**
69	* cookies: (false\|GuzzleHttp\Cookie\CookieJarInterface, default=false)
70	* Specifies whether or not cookies are used in a request or what cookie
71	* jar to use or what cookies to send. This option only works if your
72	* handler has the `cookie` middleware. Valid values are `false` and
73	* an instance of {@see Cookie\CookieJarInterface}.
74	*/
75	public const COOKIES = 'cookies';
76	/**
77	* connect_timeout: (int\|float, default=0) Number of seconds to wait while
78	* trying to connect to a server. Use 0 to wait 300 seconds (the default
79	* behavior).
80	*/
81	public const CONNECT_TIMEOUT = 'connect_timeout';
82	/**
83	* crypto_method: (int) A value describing the minimum TLS protocol
84	* version to use.
85	*
86	* This setting must be set to one of the
87	* ``STREAM_CRYPTO_METHOD_TLS*_CLIENT`` constants. PHP 7.4 or higher is
88	* required in order to use TLS 1.3, and cURL 7.34.0 or higher is required
89	* in order to specify a crypto method, with cURL 7.52.0 or higher being
90	* required to use TLS 1.3.
91	*/
92	public const CRYPTO_METHOD = 'crypto_method';
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	/**
105	* curl: (array) Raw cURL options to apply when using a built-in cURL handler.
106	*/
107	public const CURL = 'curl';
108	/**
109	* debug: (bool\|resource) Set to true or set to a PHP stream returned by
110	* fopen() enable debug output with the HTTP handler used to send a
111	* request.
112	*/
113	public const DEBUG = 'debug';
114	/**
115	* decode_content: (bool\|string, default=true) Specify whether or not
116	* Content-Encoding responses (gzip, deflate, etc.) are automatically
117	* decoded.
118	*/
119	public const DECODE_CONTENT = 'decode_content';
120	/**
121	* delay: (int\|float) The amount of time to delay before sending in
122	* milliseconds.
123	*/
124	public const DELAY = 'delay';
125	/**
126	* expect: (bool\|integer) Controls the behavior of the
127	* "Expect: 100-Continue" header.
128	*
129	* Set to `true` to enable the "Expect: 100-Continue" header for all
130	* requests that sends a body. Set to `false` to disable the
131	* "Expect: 100-Continue" header for all requests. Set to a number so that
132	* the size of the payload must be greater than the number in order to send
133	* the Expect header. Setting to a number will send the Expect header for
134	* all requests in which the size of the payload cannot be determined or
135	* where the body is not rewindable.
136	*
137	* By default, Guzzle will add the "Expect: 100-Continue" header when the
138	* size of the body of a request is greater than 1 MB and a request is
139	* using HTTP/1.1.
140	*/
141	public const EXPECT = 'expect';
142	/**
143	* form_params: (array<array-key, string\|int\|float\|bool\|null\|array>)
144	* Associative array of form field names to scalar, null, or nested array
145	* values. Sets the Content-Type header to application/x-www-form-urlencoded
146	* when no Content-Type header is already present.
147	*/
148	public const FORM_PARAMS = 'form_params';
149	/**
150	* headers: (array<array-key, string\|non-empty-array<array-key, string>>\|null)
151	* Associative array of HTTP headers. Each value MUST be a string or non-empty
152	* array of strings.
153	*/
154	public const HEADERS = 'headers';
155	/**
156	* http_errors: (bool, default=true) Set to false to disable exceptions
157	* when a non- successful HTTP response is received. By default,
158	* exceptions will be thrown for 4xx and 5xx responses. This option only
159	* works if your handler has the `httpErrors` middleware.
160	*/
161	public const HTTP_ERRORS = 'http_errors';
162	/**
163	* idn_conversion: (bool\|int\|null, default=false) A combination of IDNA_*
164	* constants for PHP's idn_to_ascii() function. Set to false or null to
165	* disable IDN support, or to true to use the default configuration
166	* (IDNA_DEFAULT constant).
167	*/
168	public const IDN_CONVERSION = 'idn_conversion';
169	/**
170	* json: (mixed) Adds JSON data to a request. The provided value is JSON
171	* encoded and a Content-Type header of application/json will be added to
172	* the request if no Content-Type header is already present.
173	*/
174	public const JSON = 'json';
175	/**
176	* multipart: (array) Array of part arrays, each containing a required
177	* "name" key mapping to the string or integer form field name, a required
178	* "contents" key mapping to any non-array value accepted by PSR-7
179	* Utils::streamFor() or a nested array of field values, an optional
180	* "headers" array of string custom header values, and an optional
181	* "filename" key mapping to a string to send as the filename in the part.
182	* "headers" and "filename" cannot be used when "contents" is an array.
183	*/
184	public const MULTIPART = 'multipart';
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	/**
272	* on_headers: (callable) A callable that is invoked when the HTTP headers
273	* of the response have been received but the body has not yet begun to
274	* download.
275	*/
276	public const ON_HEADERS = 'on_headers';
277	/**
278	* on_stats: (callable) allows you to get access to transfer statistics of
279	* a request and access the lower level transfer details of the handler
280	* associated with your client. ``on_stats`` is a callable that is invoked
281	* when a handler has finished sending a request. The callback is invoked
282	* with transfer statistics about the request, the response received, or
283	* the error encountered. Included in the data is the total amount of time
284	* taken to send the request.
285	*/
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';
297	/**
298	* progress: (callable) Defines a function to invoke when transfer
299	* progress is made. The function accepts the following positional
300	* arguments: the total number of bytes expected to be downloaded, the
301	* number of bytes downloaded so far, the number of bytes expected to be
302	* uploaded, the number of bytes uploaded so far.
303	*/
304	public const PROGRESS = 'progress';
305	/**
306	* protocols: (non-empty-array<array-key, string>, default=['http', 'https'])
307	* Allowed URI schemes. Built-in handlers accept only the case-sensitive
308	* values "http" and "https".
309	*/
310	public const PROTOCOLS = 'protocols';
311	/**
312	* proxy: (string\|array) Pass a string to specify an HTTP proxy, or an
313	* array to specify different proxies for different protocols (where the
314	* key is the protocol and the value is a proxy string or null). Provide a
315	* "no" key as a comma-delimited string, array of strings, or null to
316	* specify hosts or host-and-port pairs that should not be proxied.
317	*/
318	public const PROXY = 'proxy';
319	/**
320	* query: (array<array-key, mixed>\|string) Associative array of query string
321	* values to add to the request. This option uses PHP's http_build_query()
322	* to create the string representation. Pass a string value if you need
323	* more control than what this method provides
324	*/
325	public const QUERY = 'query';
326	/**
327	* sink: (resource\|string\|\Psr\Http\Message\StreamInterface) Where the data
328	* of the response is written to. Defaults to a PHP temp stream. Providing
329	* a string will write data to a file by the given name.
330	*/
331	public const SINK = 'sink';
332	/**
333	* synchronous: (bool) Set to true to inform HTTP handlers that you intend
334	* on waiting on the response. This can be useful for optimizations. Note
335	* that a promise is still returned if you are using one of the async
336	* client methods.
337	*/
338	public const SYNCHRONOUS = 'synchronous';
339	/**
340	* ssl_key: (array{0: string, 1?: string\|null}\|string) Specify the path to
341	* a private SSL key file. PEM is the default private key format. If a
342	* password is required, set ssl_key to an array containing the key path in
343	* the first array element followed by the key password in the second
344	* element. A null password is treated the same as omitting it. Use
345	* ssl_key_type to specify another supported key format.
346	*/
347	public const SSL_KEY = 'ssl_key';
348	/**
349	* ssl_key_type: (string) Specify the SSL private key file type.
350	*/
351	public const SSL_KEY_TYPE = 'ssl_key_type';
352	/**
353	* stream: (bool) Set to true to attempt to stream a response rather than
354	* download it all up-front.
355	*/
356	public const STREAM = 'stream';
357	/**
358	* stream_context: (array) PHP stream context options to merge into the
359	* context used by the built-in stream handler.
360	*/
361	public const STREAM_CONTEXT = 'stream_context';
362	/**
363	* verify: (bool\|string, default=true) Describes the SSL certificate
364	* verification behavior of a request. Set to true to enable SSL
365	* certificate verification using the system CA bundle when available
366	* (the default). Set to false to disable certificate verification (this
367	* is insecure!). Set to a string to provide the path to a CA bundle on
368	* disk to enable verification using a custom certificate.
369	*/
370	public const VERIFY = 'verify';
371	/**
372	* timeout: (int\|float, default=0) Number describing the timeout of the
373	* request in seconds. Use 0 to wait indefinitely (the default behavior).
374	*/
375	public const TIMEOUT = 'timeout';
376	/**
377	* read_timeout: (int\|float, default=default_socket_timeout ini setting)
378	* Number describing the body read timeout, for stream requests.
379	*/
380	public const READ_TIMEOUT = 'read_timeout';
381	/**
382	* retries: (int) Current retry count used by the retry middleware.
383	*/
384	public const RETRIES = 'retries';
385	/**
386	* version: (string\|int\|float) Specifies the HTTP protocol version to attempt
387	* to use.
388	*/
389	public const VERSION = 'version';
390	/**
391	* force_ip_resolve: (string) Set to "v4" to force IPv4 resolution or "v6"
392	* for IPv6 resolution when supported by the handler.
393	*/
394	public const FORCE_IP_RESOLVE = 'force_ip_resolve';
395	}
396