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