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