1 # namespace http\Client\Curl
3 The http\Client\Curl namespace holds option value constants specific to the curl driver of the http\Client.
5 Head down for the [list of available request options](http/Client/Curl#Options:) as well as the
6 [list of available client configuration options](http/Client/Curl#Configuration:).
10 ### Features and Versions
13 Bitmask of available libcurl features.
14 See http\Client\Curl\Features namespace.
16 List of library versions of or linked into libcurl,
17 e.g. "libcurl/7.50.0 OpenSSL/1.0.2h zlib/1.2.8 libidn/1.32 nghttp2/1.12.0".
18 See http\Client\Curl\Versions namespace.
20 ### HTTP Protocol Version
23 Use HTTP/1.0 protocol version.
25 Use HTTP/1.1 protocol version.
27 Attempt to use HTTP/2 protocol version. Available if libcurl is v7.33.0 or more recent and was built with nghttp2 support.
29 Attempt to use version 2 for HTTPS, version 1.1 for HTTP. Available if libcurl is v7.47.0 or more recent and was built with http2 support.
30 * HTTP_VERSION_2_PRIOR_KNOWLEDGE
31 Declare prior knowledge that the server supports plain (non-TLS) HTTP/2. Available if libcurl is v7.49.0 or more recent and was built with http2 support.
33 Force usage of HTTP/3. See also http\Client\Curl::$altsvc. Available if libcurl is v7.66.0 or more recent.
35 Use any HTTP protocol version.
37 ### SSL Protocol Version
40 Use TLS v1.0 encryption. Available if libcurl is v7.34.0 or more recent.
42 Use TLS v1.1 encryption. Available if libcurl is v7.34.0 or more recent.
44 Use TLS v1.2 encryption. Available if libcurl is v7.34.0 or more recent.
46 Use TLS v1.3 encryption. Available if libcurl is v7.52.0 or more recent.
48 Use any TLS v1 encryption.
50 Use SSL v2 encryption.
52 Use SSL v3 encryption.
55 * SSL_VERSION_MAX_DEFAULT
56 Use max default encryption. To be bitwise ORed to a http\Client\Curl\SSL_VERSION_ constant. Available if libcurl is v7.54.0 or more recent.
57 * SSL_VERSION_MAX_TLSv1_0
58 Use upt to TLS v1.0 encryption. To be bitwise ORed to a http\Client\Curl\SSL_VERSION_ constant. Available if libcurl is v7.54.0 or more recent.
59 * SSL_VERSION_MAX_TLSv1_1
60 Use up to TLS v1.1 encryption. To be bitwise ORed to a http\Client\Curl\SSL_VERSION_ constant. Available if libcurl is v7.54.0 or more recent.
61 * SSL_VERSION_MAX_TLSv1_2
62 Use up to TLS v1.2 encryption. To be bitwise ORed to a http\Client\Curl\SSL_VERSION_ constant. Available if libcurl is v7.54.0 or more recent.
63 * SSL_VERSION_MAX_TLSv1_3
64 Use up to TLS v1.3 encryption. To be bitwise ORed to a http\Client\Curl\SSL_VERSION_ constant. Available if libcurl is v7.54.0 or more recent.
69 Use TLS SRP authentication. Available if libcurl is v7.21.4 or more recent and was built with gnutls or openssl with TLS-SRP support.
80 ### Authentication Type
83 Don't use authentication.
85 Use Basic authentication.
87 Use Digest authentication.
89 Use IE (lower v7) quirks with Digest authentication. Available if libcurl is v7.19.3 or more recent.
91 Use NTLM authentication.
93 Use GSS-Negotiate authentication.
95 Use HTTP Netgotiate authentication (SPNEGO, RFC4559). Available if libcurl is v7.38.0 or more recent.
97 Bearer authentication. Set bearer with http\Client\Curl::$xoauth2_bearer request option. Available if libcurl is v7.61.0 or more recent.
99 Use AWS SIGv4 authentication. Available if libcurl is v7.75.0 or more recent.
101 Use any authentication.
103 ### Proxy Protocol Version
106 Use SOCKSv4 proxy protocol.
108 Use SOCKSv4a proxy protocol.
109 * PROXY_SOCKS5_HOSTNAME
110 Use SOCKS5h proxy protocol.
112 Use SOCKS5 proxy protoccol.
114 Use HTTP/1.1 proxy protocol.
116 Use HTTP/1.0 proxy protocol. Available if libcurl is v7.19.4 or more recent.
118 ### POST Redirection Behavior
121 Keep POSTing on 301 redirects. Available if libcurl is v7.19.1 or more recent.
123 Keep POSTing on 302 redirects. Available if libcurl is v7.19.1 or more recent.
125 Keep POSTing on 303 redirects. Available if libcurl is v7.19.1 or more recent.
127 Keep POSTing on any redirect. Available if libcurl is v7.19.1 or more recent.
129 ### Alt-Svc Cache Control
131 * ALTSVC_READONLYFILE
132 Do only read from but not write to the Alt-Svc cache file. Available if libcurl is v7.64.1 or more recent.
134 Accept alternative services offered over HTTP/1.1. Available if libcurl is v7.64.1 or more recent.
136 Accept alternative services offered over HTTP/2. Available if libcurl is v7.64.1 or more recent.
138 Accept alternative services offered over HTTP/3. Available if libcurl is v7.64.1 or more recent.
140 ### HSTS Cache Control
143 Enable the cache. Available if libcurl is v7.74.0 or more recent.
145 Do only read from but not write to the HSTS cache file. Available if libcurl is v7.74.0 or more recent.
149 The option names used here are more or less derived from the corresponding CURLOPT_* names.
153 The HTTP protocol version. See http\Client\Curl\HTTP_VERSION_* constants.
154 * bool $http09_allowed
155 Allow HTTP/0.9 responses. Available if libcurl is v7.64.0 or more recent. Prior to v7.64.0, responses without headers were treated as HTTP/0.9 responses and uncoditionally allowed. Enable this option to restore that behavior.
160 The hostname of the proxy.
162 See http\Client\Curl\PROXY_* constants.
164 The port number of the proxy.
168 See http\Client\Curl\AUTH_* constants.
170 Tunnel all operations through the proxy.
172 Comma separated list of hosts where no proxy should be used. Available if libcurl is v7.19.4 or more recent.
174 List of key/value pairs of headers which should only be sent to a proxy. Available if libcurl is v7.37.0 or more recent.
175 * string $proxy_service_name
176 Proxy service name. The default service name is "HTTP" for HTTP based proxies and "rcmd" for SOCKS5. Available if libcurl is v7.43.0 or more recent and has built-in GSSAPI support.
178 SOCKS5 proxy authentication type. Available if libcurl is v7.55.0 or more recent.
180 * http\Client\Curl\AUTH_NONE
181 * http\Client\Curl\AUTH_BASIC
182 * http\Client\Curl\AUTH_GSSNEG
183 * bool $haproxy_protocol
184 Send special [HAProxy protocol](https://github.com/haproxy/haproxy/blob/master/doc/proxy-protocol.txt) preamble. Available if libcurl is v7.60.0 or more recent.
188 * int $dns_cache_timeout
189 Resolved hosts will be kept fot this number of seconds.
191 See http\Client\Curl\IPRESOLVE_* constants.
193 A list of HOST:PORT:ADDRESS mappings which pre-populate the DNS cache. Available if libcurl is v7.21.3 or more recent.
194 * string $dns_servers
195 Comma separated list of custom DNS servers of the form HOST[:PORT]. Available if libcurl is v7.24.0 or more recent and has built-in c-ares support.
196 * string $dns_interface
197 The name of the network interface ***name*** that the DNS resolver should bind to. Available if libcurl is v7.33.0 or more recent and has built-in c-ares support.
198 * string $dns_local_ip4
199 The local IPv4 ***address*** that the resolver should bind to. Available if libcurl is v7.33.0 or more recent and has built-in c-ares support.
200 * string $dns_local_ip6
201 The local IPv6 ***address*** that the resolver should bind to. Available if libcurl is v7.33.0 or more recent and has built-in c-ares support.
202 * bool $dns_shuffle_addresses
203 Enforce shuffling DNS addresses returned from the system. Available if libcurl is v7.60.0 or more recent.
205 URL to use for DNS-over-HTTPS. Note the HTTPS. Available if libcurl is v7.62.0 or more recent.
209 * int $low_speed_limit
210 Minimum speed in bytes per second.
211 * int $low_speed_time
212 Maximum time in seconds the transfer can be below $low_speed_limit before cancelling.
214 Maximum download size.
216 Maximum time in seconds an idle connection is checked to still be alive for a new transfer. Defaults to 118 seconds. Available if libcurl is v7.65.0 or more recent.
218 ### Connection handling
220 * bool $fresh_connect
221 Force a new connection.
223 Force closing the connection.
228 Outgoing interface name.
230 A tuple of min/max ports.
232 Override the URL's port.
234 RFC4007 zone_id. Available if libcurl is v7.19.0 or more recent.
235 * bool $tcp_keepalive
236 Whether to use TCP keepalive. Available if libcurl is v7.25.0 or more recent.
238 Seconds to wait before sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
240 Interval in seconds to wait between sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
242 Disable [Nagle's algotrithm](http://tools.ietf.org/html/rfc896).
244 Enable [TCP Fast Open](http://tools.ietf.org/html/rfc7413) on supported platforms.
245 * string $unix_socket_path
246 Connect to the webserver listening at $unix_socket_path instead of opening a TCP connection to it. Available if libcurl is v7.40.0 or more recent and has built-in unix socket support.
247 * string $abstract_unix_socket
248 Similar to $unix_socket_path but for abstract namespaces independent of the filesystem. The preceding NULL byte is adedd automatically. Available if libcurl is v7.53.0 on supporting platforms and has built-in unix socket support.
250 Do *not* squash sequences of "/../" or "/./" that may exist in the URL's path.
257 See http\Client\Curl\AUTH_* constants.
258 * string $service_name
259 The name of the service for DIGEST-MD5, SPNEGO and KERBEROS5 authentication mechanisms. The default service name is "HTTP". Available if libcurl is v7.43.0 or more recent.
260 * string $xoauth2_bearer
261 Bearer token for http\Client\Curl\AUTH_BEARER. Available if libcurl is v7.61.0 or more recent.
263 Provide AWS V4 signature authentication in the form of `provider1[:provider2[:region[:service]]]`. Defaults to `aws:amz` if http\Client\Curl\AUTH_AWS_SIGV4 was used for $httpauthtype. Available if libcurl is v7.75.0 or more recent.
268 How many redirects to follow.
269 * bool $unrestricted_auth
270 Whether to keep sending authentication credentials on redirects to different hosts.
272 See http\Client\Curl\POSTREDIR_* constants. Available if libcurl is v7.19.1 or more recent.
279 Pause this number of seconds between retries.
284 Custom Referer header.
286 Whether to automatically send referers.
288 Custom User-Agent header. Setting this option to NULL will use the default user agent, use the empty string to prevent this header being sent at all.
292 Whether to request compressed content (through Accept-Encoding).
294 Custom If-(Un)Modified since time. If less than zero, the current time will be added.
296 Specify a file name to use as `Alt-Svc` cache. Available if libcurl is v7.64.1 or more recent.
298 Specify how to handle `Alt-Svc` announcements as a bitmask of http\Client\Curl\ALTSVC_* constants. Available if libcurl is v7.64.1 or more recent.
300 Specify a file name to use as HSTS cache. Availalbe if libcurl is v7.74.0 or more recent.
302 Specify how to handle the HSTS cache as a bitmask of http\Client\Curl\HSTS_* constatns. Available if libcurl is v7.74.0
307 Resume from this byte offset.
309 Fetch specific ranges (if server supports byte ranges).
313 * bool $encodecookies
314 Whether to URLencode cookies.
316 List of custom cookies in the form ["name" => "value"].
317 * bool $cookiesession
318 Ignore previous session cookies to be loaded from $cookiestore.
319 * string $cookiestore
320 Path to a Netscape cookie file, from which cookies will be loaded resp. to which cookies will be written.
325 Seconds the complete transfer may take.
326 * float $connecttimeout
327 Seconds the connect may take.
328 * float $expect_100_timeout
329 Senconds to wait for the server to send a response to "Expect: 100-Continue" before just proceeding with the request. Available if libcurl is v7.36.0 or more recent.
334 Subarray of SSL related options:
336 SSL certificate file.
338 Certificate type (DER, PEM). (Secure Transport additionally supports P12).
342 PK type (PEM, DER, ENG).
344 The password for the private key.
346 Crypto engine to use for the private key.
348 See http\Client\Curl\SSL_VERSION_* constants.
350 Whether to apply peer verification.
352 Whether to apply host verification.
353 * string $cipher_list
354 One or more cipher strings separated by colons.
356 CA bundle to verify the peer with.
358 Directory with prepared CA certs to verify the peer with.
359 * string $random_file
360 A file used to read from to seed the random engine.
362 A Entropy Gathering Daemon socket.
364 CA PEM cert file for peer verification. Available if libcurl is v7.19.0 or more recent.
366 File with the concatenation of CRL in PEM format. Available if libcurl was built with OpenSSL support.
368 Enable gathering of SSL certificate chain information. Available if libcurl is v7.19.1 or more recent.
369 * string $pinned_publickey
370 File with a public key to pin. Available if libcurl is v7.39.0 or more recent.
372 TLS_AUTH_* constant. Available if libcurl is v7.21.4 or more recent.
373 * string $tlsauthuser
374 TLS-SRP username. Available if libcurl is v7.21.4 or more recent.
375 * string $tlsauthpass
376 TLS-SRP password. Available if libcurl is v7.21.4 or more recent.
378 Enable OCSP. Available if libcurl is v7.41.0 or more recent and was built with OpenSSL, GnuTLS or NSS support.
380 Whether false start should be used during the TLS handshake. Available if libcurl is v7.42.0 or more recent and was built with NSS or SecureTransport support.
381 * string $tls13_ciphers
382 TLSv1.3 cipher list. Available if libcurl is v7.61.0 or more recent.
384 Subarray of SSL related options to use for the proxy:
385 > See the respective $ssl options above for descriptions.
387 Available if libcurl is v7.52.0 or more recent.
389 Available if libcurl is v7.52.0 or more recent.
391 Available if libcurl is v7.52.0 or more recent.
393 Available if libcurl is v7.52.0 or more recent.
395 Available if libcurl is v7.52.0 or more recent.
397 Available if libcurl is v7.52.0 or more recent.
399 Available if libcurl is v7.52.0 or more recent.
401 Available if libcurl is v7.52.0 or more recent.
402 * string $cipher_list
403 Available if libcurl is v7.52.0 or more recent.
405 Available if libcurl is v7.52.0 or more recent.
407 Available if libcurl is v7.52.0 or more recent.
409 Available if libcurl is v7.52.0 or more recent.
410 * string $pinned_publickey
411 Available if libcurl is v7.52.0 or more recent.
413 Available if libcurl is v7.52.0 or more recent.
414 * string $tlsauthuser
415 Available if libcurl is v7.52.0 or more recent.
416 * string $tlsauthpass
417 Available if libcurl is v7.52.0 or more recent.
418 * string $pinned_publickey
419 Available if libcurl is v7.59.0 or more recent.
420 * string $tls13_ciphers
421 Available if libcurl is v7.61.0 or more recent.
423 Available if libcurl is v7.71.0 or more recent.
428 Size of the connection cache.
429 * int $max_host_connections
430 Maximum number of connections to a single host. Available if libcurl is v7.30.0 or more recent.
431 * int $max_pipeline_length
432 Maximum number of requests in a pipeline. Available if libcurl is v7.30.0 or more recent.
433 * int $max_total_connections
434 Maximum number of simultaneous open connections of this client. Available if libcurl is v7.30.0 or more recent.
435 * int $max_concurrent_streams
436 Maximum count of simultanous streams to support over one HTTP/2 connection. Defaults to 100. Available if libcurl is v7.67.0 or more recent.
438 Whether to enable HTTP/1.1 pipelining. Available if libcurl is **not** v7.62.0 or more recent.
439 * int $chunk_length_penalty_size
440 Chunk length threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent, but less than v7.62.0.
441 * int $content_length_penalty_size
442 Size threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent, but less than v7.62.0.
443 * array $pipelining_server_bl
444 Simple list of server software names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent, but less than v7.62.0.
445 * array $pipelining_site_bl
446 Simple list of server host names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent, but less than v7.62.0.
447 * mixed $use_eventloop
448 Whether to use an event loop. This option accepts either bool, whether to use
449 the internal event loop, or an instance of an http\Client\Curl\User implementation.
450 The internal event loop is only available if pecl/http was built with libevent support.
451 * bool $share_cookies
452 Whether to let the client share cookies between requests.
454 Whether to let the client share SSL/TLS sessions between requests. Available if libcurl is v7.23.0 or more recent.