git.m6w6.name Git - mdref/mdref-http/blob - http/Client/Curl.md

   1 # namespace http\Client\Curl
   2
   3 The http\Client\Curl namespace holds option value constants specific to the curl driver of the http\Client.
   4
   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:).
   7
   8 ## Constants:
   9
  10 ### Features and Versions
  11
  12 * FEATURES
  13   Bitmask of available libcurl features.
  14   See http\Client\Curl\Features namespace.
  15 * VERSIONS
  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.
  19
  20 ### HTTP Protocol Version
  21
  22 * HTTP_VERSION_1_0
  23   Use HTTP/1.0 protocol version.
  24 * HTTP_VERSION_1_1
  25   Use HTTP/1.1 protocol version.
  26 * HTTP_VERSION_2_0
  27   Attempt to use HTTP/2 protocol version. Available if libcurl is v7.33.0 or more recent and was built with nghttp2 support.
  28 * HTTP_VERSION_2TLS
  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.
  32 * HTTP_VERSION_3
  33   Force usage of HTTP/3. See also http\Client\Curl::$altsvc. Available if libcurl is v7.66.0 or more recent.
  34 * HTTP_VERSION_ANY
  35   Use any HTTP protocol version.
  36
  37 ### SSL Protocol Version
  38
  39 * SSL_VERSION_TLSv1_0
  40   Use TLS v1.0 encryption. Available if libcurl is v7.34.0 or more recent.
  41 * SSL_VERSION_TLSv1_1
  42   Use TLS v1.1 encryption. Available if libcurl is v7.34.0 or more recent.
  43 * SSL_VERSION_TLSv1_2
  44   Use TLS v1.2 encryption. Available if libcurl is v7.34.0 or more recent.
  45 * SSL_VERSION_TLSv1_3
  46   Use TLS v1.3 encryption. Available if libcurl is v7.52.0 or more recent.
  47 * SSL_VERSION_TLSv1
  48   Use any TLS v1 encryption.
  49 * SSL_VERSION_SSLv2
  50   Use SSL v2 encryption.
  51 * SSL_VERSION_SSLv3
  52   Use SSL v3 encryption.
  53 * SSL_VERSION_ANY
  54   Use any 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.
  65
  66 ### TLS Auth Types
  67
  68 * TLSAUTH_SRP
  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.
  70
  71 ### DNS IP Version
  72
  73 * IPRESOLVE_V4
  74   Use IPv4 resolver.
  75 * IPRESOLVE_V6
  76   Use IPv6 resolver.
  77 * IPRESOLVE_ANY
  78   Use any resolver.
  79
  80 ### Authentication Type
  81
  82 * AUTH_NONE
  83   Don't use authentication.
  84 * AUTH_BASIC
  85   Use Basic authentication.
  86 * AUTH_DIGEST
  87   Use Digest authentication.
  88 * AUTH_DIGEST_IE
  89   Use IE (lower v7) quirks with Digest authentication. Available if libcurl is v7.19.3 or more recent.
  90 * AUTH_NTLM
  91   Use NTLM authentication.
  92 * AUTH_GSSNEG
  93   Use GSS-Negotiate authentication.
  94 * AUTH_SPNEGO
  95   Use HTTP Netgotiate authentication (SPNEGO, RFC4559). Available if libcurl is v7.38.0 or more recent.
  96 * AUTH_BEARER
  97   Bearer authentication. Set bearer with http\Client\Curl::$xoauth2_bearer request option. Available if libcurl is v7.61.0 or more recent.
  98 * AUTH_AWS_SIGV4
  99   Use AWS SIGv4 authentication. Available if libcurl is v7.75.0 or more recent.
 100 * AUTH_ANY
 101   Use any authentication.
 102
 103 ### Proxy Protocol Version
 104
 105 * PROXY_SOCKS4
 106   Use SOCKSv4 proxy protocol.
 107 * PROXY_SOCKS4A
 108   Use SOCKSv4a proxy protocol.
 109 * PROXY_SOCKS5_HOSTNAME
 110   Use SOCKS5h proxy protocol.
 111 * PROXY_SOCKS5
 112   Use SOCKS5 proxy protoccol.
 113 * PROXY_HTTP
 114   Use HTTP/1.1 proxy protocol.
 115 * PROXY_HTTP_1_0
 116   Use HTTP/1.0 proxy protocol. Available if libcurl is v7.19.4 or more recent.
 117
 118 ### POST Redirection Behavior
 119
 120 * POSTREDIR_301
 121   Keep POSTing on 301 redirects. Available if libcurl is v7.19.1 or more recent.
 122 * POSTREDIR_302
 123   Keep POSTing on 302 redirects. Available if libcurl is v7.19.1 or more recent.
 124 * POSTREDIR_303
 125   Keep POSTing on 303 redirects. Available if libcurl is v7.19.1 or more recent.
 126 * POSTREDIR_ALL
 127   Keep POSTing on any redirect. Available if libcurl is v7.19.1 or more recent.
 128
 129 ### Alt-Svc Cache Control
 130
 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.
 133 * ALTSVC_H1
 134   Accept alternative services offered over HTTP/1.1. Available if libcurl is v7.64.1 or more recent.
 135 * ALTSVC_H2
 136   Accept alternative services offered over HTTP/2. Available if libcurl is v7.64.1 or more recent.
 137 * ALTSVC_H3
 138   Accept alternative services offered over HTTP/3. Available if libcurl is v7.64.1 or more recent.
 139
 140 ### HSTS Cache Control
 141
 142 * HSTS_ENABLE
 143   Enable the cache. Available if libcurl is v7.74.0 or more recent.
 144 * HSTS_READONLYFILE
 145   Do only read from but not write to the HSTS cache file. Available if libcurl is v7.74.0 or more recent.
 146
 147 ## Options:
 148
 149 The option names used here are more or less derived from the corresponding CURLOPT_* names.
 150 ### HTTP
 151
 152 * int $protocol
 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.
 156
 157 ### Proxies
 158
 159 * string $proxyhost
 160   The hostname of the proxy.
 161 * int $proxytype
 162   See http\Client\Curl\PROXY_* constants.
 163 * int $proxyport
 164   The port number of the proxy.
 165 * string $proxyauth
 166   user:password
 167 * int $proxyauthtype
 168   See http\Client\Curl\AUTH_* constants.
 169 * bool $proxytunnel
 170   Tunnel all operations through the proxy.
 171 * string $noproxy
 172   Comma separated list of hosts where no proxy should be used. Available if libcurl is v7.19.4 or more recent.
 173 * array $proxyheader
 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.
 177 * int $socks5_auth
 178   SOCKS5 proxy authentication type. Available if libcurl is v7.55.0 or more recent.
 179   Available settings:
 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.
 185
 186 ### DNS
 187
 188 * int $dns_cache_timeout
 189   Resolved hosts will be kept fot this number of seconds.
 190 * int $ipresolve
 191   See http\Client\Curl\IPRESOLVE_* constants.
 192 * array $resolve
 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.
 204 * string $doh_url
 205   URL to use for DNS-over-HTTPS. Note the HTTPS. Available if libcurl is v7.62.0 or more recent.
 206
 207 ### Limits
 208
 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.
 213 * int $maxfilesize
 214   Maximum download size.
 215 * int $maxage_conn
 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.
 217
 218 ### Connection handling
 219
 220 * bool $fresh_connect
 221   Force a new connection.
 222 * bool $forbid_reuse
 223   Force closing the connection.
 224
 225 ### Networking
 226
 227 * string $interface
 228   Outgoing interface name.
 229 * array $portrange
 230   A tuple of min/max ports.
 231 * int $port
 232   Override the URL's port.
 233 * int $address_scope
 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.
 237 * int $tcp_keepidle
 238   Seconds to wait before sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
 239 * int $tcp_keepintvl
 240   Interval in seconds to wait between sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
 241 * bool $tcp_nodelay
 242   Disable [Nagle's algotrithm](http://tools.ietf.org/html/rfc896).
 243 * bool $tcp_fastopen
 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.
 249 * bool $path_as_is
 250   Do *not* squash sequences of "/../" or "/./" that may exist in the URL's path.
 251
 252 ### Authentication
 253
 254 * string $httpauth
 255   user:password
 256 * int $httpauthtype
 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.
 262 * string $aws_sigv4
 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.
 264
 265 ### Redirection
 266
 267 * int $redirect
 268   How many redirects to follow.
 269 * bool $unrestricted_auth
 270   Whether to keep sending authentication credentials on redirects to different hosts.
 271 * int $postredir
 272   See http\Client\Curl\POSTREDIR_* constants. Available if libcurl is v7.19.1 or more recent.
 273
 274 ### Retries
 275
 276 * int $retrycount
 277   Retry this often.
 278 * float $retrydelay
 279   Pause this number of seconds between retries.
 280
 281 ### Special headers
 282
 283 * string $referer
 284   Custom Referer header.
 285 * bool $autoreferer
 286   Whether to automatically send referers.
 287 * string $useragent
 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.
 289 * string $etag
 290   Custom ETag.
 291 * bool $compress
 292   Whether to request compressed content (through Accept-Encoding).
 293 * int $lastmodified
 294   Custom If-(Un)Modified since time. If less than zero, the current time will be added.
 295 * string $altsvc
 296   Specify a file name to use as `Alt-Svc` cache. Available if libcurl is v7.64.1 or more recent.
 297 * int $altsvc_ctrl
 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.
 299 * string $hsts
 300   Specify a file name to use as HSTS cache. Availalbe if libcurl is v7.74.0 or more recent.
 301 * int $hsts_ctrl
 302   Specify how to handle the HSTS cache as a bitmask of http\Client\Curl\HSTS_* constatns. Available if libcurl is v7.74.0
 303
 304 ### Resume/Ranges
 305
 306 * int $resume
 307   Resume from this byte offset.
 308 * array $range
 309   Fetch specific ranges (if server supports byte ranges).
 310
 311 ### Cookies
 312
 313 * bool $encodecookies
 314   Whether to URLencode cookies.
 315 * array $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.
 321
 322 ### Timeouts
 323
 324 * float $timeout
 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.
 330
 331 ### SSL
 332
 333 * array $ssl
 334   Subarray of SSL related options:
 335   * string $cert
 336     SSL certificate file.
 337   * string $certtype
 338     Certificate type (DER, PEM). (Secure Transport additionally supports P12).
 339   * string $key
 340     Private key file.
 341   * string $keytype
 342     PK type (PEM, DER, ENG).
 343   * string $keypasswd
 344     The password for the private key.
 345   * string $engine
 346     Crypto engine to use for the private key.
 347   * int $version
 348     See http\Client\Curl\SSL_VERSION_* constants.
 349   * bool $verifypeer
 350     Whether to apply peer verification.
 351   * bool $verifyhost
 352     Whether to apply host verification.
 353   * string $cipher_list
 354     One or more cipher strings separated by colons.
 355   * string $cainfo
 356     CA bundle to verify the peer with.
 357   * string $capath
 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.
 361   * string $egdsocket
 362     A Entropy Gathering Daemon socket.
 363   * string $issuercert
 364     CA PEM cert file for peer verification. Available if libcurl is v7.19.0 or more recent.
 365   * string $crlfile
 366     File with the concatenation of CRL in PEM format. Available if libcurl was built with OpenSSL support.
 367   * bool $certinfo
 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.
 371   * int $tlsauthtype
 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.
 377   * bool $verifystatus
 378     Enable OCSP. Available if libcurl is v7.41.0 or more recent and was built with OpenSSL, GnuTLS or NSS support.
 379   * bool $falsestart
 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.
 383 * array $proxy_ssl
 384   Subarray of SSL related options to use for the proxy:
 385   > See the respective $ssl options above for descriptions.
 386   * string $cert
 387     Available if libcurl is v7.52.0 or more recent.
 388   * string $certtype
 389     Available if libcurl is v7.52.0 or more recent.
 390   * string $key
 391     Available if libcurl is v7.52.0 or more recent.
 392   * string $keytype
 393     Available if libcurl is v7.52.0 or more recent.
 394   * string $keypasswd
 395     Available if libcurl is v7.52.0 or more recent.
 396   * int $version
 397     Available if libcurl is v7.52.0 or more recent.
 398   * bool $verifypeer
 399     Available if libcurl is v7.52.0 or more recent.
 400   * bool $verifyhost
 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.
 404   * string $cainfo
 405     Available if libcurl is v7.52.0 or more recent.
 406   * string $capath
 407     Available if libcurl is v7.52.0 or more recent.
 408   * string $crlfile
 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.
 412   * int $tlsauthtype
 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.
 422   * string $issuercert
 423     Available if libcurl is v7.71.0 or more recent.
 424
 425 ## Configuration:
 426
 427 * int $maxconnects
 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.
 437 * bool $pipelining
 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.
 453 * bool $share_ssl
 454   Whether to let the client share SSL/TLS sessions between requests. Available if libcurl is v7.23.0 or more recent.