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 ## Changelog
   6
   7 Version | Change
   8 --------|-------
   9 2.1.0   | Added $dns_interface, $dns_local_ip4, $dns_local_ip6 and $expect_100_timeout options.
  10 2.1.2   | Added request option constants:<br> http\Client\Curl\POSTREDIR_303,<br> http\Client\Curl\AUTH_SPNEGO,<br> http\Client\Curl\SSL_VERSION_TLSv1_0,<br> http\Client\Curl\SSL_VERSION_TLSv1_1 and<br> http\Client\Curl\SSL_VERSION_TLSv1_2
  11 2.3.0   | Added $pinned_publickey, $ltsauth and $verifystatus $ssl options.<br>Added $proxyheader and $unix_socket_path options.<br>Added request option constants:<br>http\Client\Curl\HTTP_VERSION_2_0 and<br>http\Client\Curl\TLS_AUTH_SRP.
  12
  13 ## Constants:
  14
  15 ### HTTP Protocol Version
  16
  17 * HTTP_VERSION_1_0
  18   Use HTTP/1.0 protocol version.
  19 * HTTP_VERSION_1_1
  20   Use HTTP/1.1 protocol version.
  21 * HTTP_VERSION_2_0
  22   Use HTTP/2 protocol version. Available if libcurl is v7.33.0 or more recent and was built with nghttp2 support.
  23 * HTTP_VERSION_ANY
  24   Use any HTTP protocol version.
  25
  26 ### SSL Protocol Version
  27
  28 * SSL_VERSION_TLSv1_0
  29   Use TLS v1.0 encryption.
  30 * SSL_VERSION_TLSv1_1
  31   Use TLS v1.1 encryption.
  32 * SSL_VERSION_TLSv1_2
  33   Use TLS v1.2 encryption.
  34 * SSL_VERSION_TLSv1
  35   Use any TLS v1 encryption.
  36 * SSL_VERSION_SSLv2
  37   Use SSL v2 encryption.
  38 * SSL_VERSION_SSLv3
  39   Use SSL v3 encryption.
  40 * SSL_VERSION_ANY
  41   Use any encryption.
  42
  43 ### TLS Auth Types
  44
  45 * TLS_AUTH_SRP
  46   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.
  47
  48 ### DNS IP Version
  49
  50 * IPRESOLVE_V4
  51   Use IPv4 resolver.
  52 * IPRESOLVE_V6
  53   Use IPv6 resolver.
  54 * IPRESOLVE_ANY
  55   Use any resolver.
  56
  57 ### Authentication Type
  58
  59 * AUTH_BASIC
  60   Use Basic authentication.
  61 * AUTH_DIGEST
  62   Use Digest authentication.
  63 * AUTH_DIGEST_IE
  64   Use IE (lower v7) quirks with Digest authentication. Available if libcurl is v7.19.3 or more recent.
  65 * AUTH_NTLM
  66   Use NTLM authentication.
  67 * AUTH_GSSNEG
  68   Use GSS-Negotiate authentication.
  69 * AUTH_SPNEGO
  70   Use HTTP Netgotiate authentication (SPNEGO, RFC4559). Available if libcurl is v7.38.0 or more recent.
  71 * AUTH_ANY
  72   Use any authentication.
  73
  74 ### Proxy Protocol Version
  75
  76 * PROXY_SOCKS4
  77   Use SOCKSv4 proxy protocol.
  78 * PROXY_SOCKS4A
  79   Use SOCKSv4a proxy protocol.
  80 * PROXY_SOCKS5_HOSTNAME
  81   Use SOCKS5h proxy protocol.
  82 * PROXY_SOCKS5
  83   Use SOCKS5 proxy protoccol.
  84 * PROXY_HTTP
  85   Use HTTP/1.1 proxy protocol.
  86 * PROXY_HTTP_1_0
  87   Use HTTP/1.0 proxy protocol. Available if libcurl is v7.19.4 or more recent.
  88
  89 ### POST Redirection Behavior
  90
  91 * POSTREDIR_301
  92   Keep POSTing on 301 redirects. Available if libcurl is v7.19.1 or more recent.
  93 * POSTREDIR_302
  94   Keep POSTing on 302 redirects. Available if libcurl is v7.19.1 or more recent.
  95 * POSTREDIR_303
  96   Keep POSTing on 303 redirects. Available if libcurl is v7.19.1 or more recent.
  97 * POSTREDIR_ALL
  98   Keep POSTing on any redirect. Available if libcurl is v7.19.1 or more recent.
  99
 100
 101 ## Options:
 102
 103 The option names used here are more or less derived from the corresponding CURLOPT_* names.
 104 ### HTTP
 105
 106 * int $protocol
 107   The HTTP protocol version. See http\Client\Curl\HTTP_VERSION_* constants.
 108
 109 ### Proxies
 110
 111 * string $proxyhost
 112   The hostname of the proxy.
 113 * int $proxytype
 114   See http\Client\Curl\PROXY_* constants.
 115 * int $proxyport
 116   The port number of the proxy.
 117 * string $proxyauth
 118   user:password
 119 * int $proxyauthtype
 120   See http\Client\Curl\AUTH_* constants.
 121 * bool $proxytunnel
 122   Tunnel all operations through the proxy.
 123 * string $noproxy
 124   Comma separated list of hosts where no proxy should be used. Available if libcurl is v7.19.4 or more recent.
 125 * array $proxyheader
 126   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.
 127
 128 ### DNS
 129
 130 * int $dns_cache_timeout
 131   Resolved hosts will be kept fot this number of seconds.
 132 * int $ipresolve
 133   See http\Client\Curl\IPRESOLVE_* constants.
 134 * array $resolve
 135   A list of HOST:PORT:ADDRESS mappings which pre-populate the DNS cache. Available if libcurl is v7.21.3 or more recent.
 136 * string $dns_servers
 137   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.
 138 * string $dns_interface
 139   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.
 140 * string $dns_local_ip4
 141   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.
 142 * string $dns_local_ip6
 143   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.
 144
 145 ### Limits
 146
 147 * int $low_speed_limit
 148   Minimum speed in bytes per second.
 149 * int $low_speed_time
 150   Maximum time in seconds the transfer can be below $low_speed_limit before cancelling.
 151 * int $maxfilesize
 152   Maximum download size.
 153
 154 ### Connection handling
 155
 156 * bool $fresh_connect
 157   Force a new connection.
 158 * bool $forbid_reuse
 159   Force closing the connection.
 160
 161 ### Networking
 162
 163 * string $interface
 164   Outgoing interface name.
 165 * array $portrange
 166   A tuple of min/max ports.
 167 * int $port
 168   Override the URL's port.
 169 * int $address_scope
 170   RFC4007 zone_id. Available if libcurl is v7.19.0 or more recent.
 171 * bool $tcp_keepalive
 172   Whether to use TCP keepalive. Available if libcurl is v7.25.0 or more recent.
 173 * int $tcp_keepidle
 174   Seconds to wait before sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
 175 * int $tcp_keepintvl
 176   Interval in seconds to wait between sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
 177 * bool $tcp_nodelay
 178   Disable [Nagle's algotrithm](http://tools.ietf.org/html/rfc896).
 179 * string $unix_socket_path
 180   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.
 181
 182 ### Authentication
 183
 184 * string $httpauth
 185   user:password
 186 * int $httpauthtype
 187   See http\Client\Curl\AUTH_* constants.
 188
 189 ### Redirection
 190
 191 * int $redirect
 192   How many redirects to follow.
 193 * bool $unrestricted_auth
 194   Whether to keep sending authentication credentials on redirects to different hosts.
 195 * int $postredir
 196   See http\Client\Curl\POSTREDIR_* constants. Available if libcurl is v7.19.1 or more recent.
 197
 198 ### Retries
 199
 200 * int $retrycount
 201   Retry this often.
 202 * float $retrydelay
 203   Pause this number of seconds between retries.
 204
 205 ### Special headers
 206
 207 * string $referer
 208   Custom Referer header.
 209 * bool $autoreferer
 210   Whether to automatically send referers.
 211 * string $useragent
 212   Custom User-Agent header.
 213 * string $etag
 214   Custom ETag.
 215 * bool $compress
 216   Whether to request compressed content (through Accept-Encoding).
 217 * int $lastmodified
 218   Custom If-(Un)Modified since time. If less than zero, the current time will be added.
 219
 220 ### Resume/Ranges
 221
 222 * int $resume
 223   Resume from this byte offset.
 224 * array $range
 225   Fetch specific ranges (if server supports byte ranges).
 226
 227 ### Cookies
 228
 229 * bool $encodecookies
 230   Whether to URLencode cookies.
 231 * array $cookies
 232   List of custom cookies in the form ["name" => "value"].
 233 * bool $cookiesession
 234   Ignore previous session cookies to be loaded from $cookiestore.
 235 * string $cookiestore
 236   Path to a Netscape cookie file, from which cookies will be loaded resp. to which cookies will be written.
 237
 238 ### Timeouts
 239
 240 * float $timeout
 241   Seconds the complete transfer may take.
 242 * float $connecttimeout
 243   Seconds the connect may take.
 244 * float $expect_100_timeout
 245   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.
 246
 247 ### SSL
 248
 249 * array $ssl
 250   Subarray of SSL related options:
 251   * string $cert
 252     SSL certificate file.
 253   * string $certtype
 254     Certificate type (DER, PEM). (Secure Transport additionally supports P12).
 255   * string $key
 256     Private key file.
 257   * string $keytype
 258     PK type (PEM, DER, ENG).
 259   * string $keypasswd
 260     The password for the private key.
 261   * string $engine
 262     Crypto engine to use for the private key.
 263   * int $version
 264     See http\Client\Curl\SSL_VERSION_* constants.
 265   * bool $verifypeer
 266     Whether to apply peer verification.
 267   * bool $verifyhost
 268     Whether to apply host verification.
 269   * string $cipher_list
 270     One or more cipher strings separated by colons.
 271   * string $cainfo
 272     CA bundle to verify the peer with.
 273   * string $capath
 274     Directory with prepared CA certs to verify the peer with.
 275   * string $random_file
 276     A file used to read from to seed the random engine.
 277   * string $egdsocket
 278     A Entropy Gathering Daemon socket.
 279   * string $issuercert
 280     CA PEM cert for peer verification. Available if libcurl is v7.19.0 or more recent.
 281   * string $crlfile
 282     File with the concatenation of CRL in PEM format. Available if libcurl was built with OpenSSL support.
 283   * bool $certinfo
 284     Enable gathering of SSL certificate chain information. Available if libcurl is v7.19.1 or more recent.
 285   * string $pinned_publickey
 286     File with a public key to pin. Available if libcurl is v7.39.0 or more recent.
 287   * int $tlsauthtype
 288     TLS_AUTH_* constant. Available if libcurl is v7.21.4 or more recent.
 289   * string $tlsauthuser
 290     TLS-SRP username. Available if libcurl is v7.21.4 or more recent.
 291   * string $lsauthpass
 292     TLS-SRP password. Available if libcurl is v7.21.4 or more recent.
 293   * bool $verifystatus
 294     Enable OCSP. Available if libcurl is v7.41.0 or more recent and was build with openssl, gnutls or nss support.
 295
 296 ## Configuration:
 297
 298 * int $maxconnects
 299   Size of the connection cache.
 300 * int $max_host_connections
 301   Maximum number of connections to a single host. Available if libcurl is v7.30.0 or more recent.
 302 * int $max_pipeline_length
 303   Maximum number of requests in a pipeline. Available if libcurl is v7.30.0 or more recent.
 304 * int $max_total_connections
 305   Maximum number of simultaneous open connections of this client. Available if libcurl is v7.30.0 or more recent.
 306 * bool $pipelining
 307   Whether to enable HTTP/1.1 pipelining.
 308 * int $chunk_length_penalty_size
 309   Chunk length threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent.
 310 * int $content_length_penalty_size
 311   Size threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent.
 312 * array $pipelining_server_bl
 313   Simple list of server software names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent.
 314 * array $pipelining_site_bl
 315   Simple list of server host names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent.
 316 * bool $use_eventloop
 317   Whether to use an event loop. Available if pecl/http was built with libevent support.