From 961f8a1687d70d07e07979cdd0c725f62ac4121f Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Fri, 13 Feb 2015 18:19:59 +0100 Subject: [PATCH] preliminary 2.3.0 docs --- http.md | 4 + http/Client.md | 6 + http/Client/Curl.md | 65 ++++++-- http/Client/Request/addSslOptions.md | 2 +- http/Client/Request/setSslOptions.md | 2 +- http/Client/addSslOptions.md | 2 +- http/Client/configure.md | 30 ++++ http/Client/enableEvents.md | 9 ++ http/Client/enablePipelining.md | 9 ++ http/Client/getAvailableConfiguration.md | 52 +++++++ http/Client/getAvailableOptions.md | 179 +++++++++++++++++++++++ http/Client/getTransferInfo.md | 3 - http/Client/setSslOptions.md | 2 +- 13 files changed, 348 insertions(+), 17 deletions(-) create mode 100644 http/Client/configure.md create mode 100644 http/Client/getAvailableConfiguration.md create mode 100644 http/Client/getAvailableOptions.md diff --git a/http.md b/http.md index 0a1c87d..e78795a 100644 --- a/http.md +++ b/http.md @@ -25,6 +25,7 @@ The following system libraries are required to build this extension: =zlib= Provides gzip/zlib/deflate encoding. + Minimum version: 1.2.0.4 Install on Debian: `apt-get install zlib1g-dev` @@ -34,15 +35,18 @@ The following system libraries are optional and provide additional features: =libidn= Provides IDNA support in URLs. + Minimum version: none Install on Debian: `apt-get install libidn11-dev` =libcurl= Provides HTTP request functionality. + Minimum version: 7.18.2 Install on Debian: `apt-get install libcurl4-openssl-dev` Note: There are usually different styles of SSL support for libcurl available, so you can replace 'openssl' in the above command f.e. with 'nss' or 'gnutls'. =libevent= Eventloop support for the HTTP client. + Minimum version: none Install on Debian: `apt-get install libevent-dev` ### PHP extensions: diff --git a/http/Client.md b/http/Client.md index d86ad75..14626a7 100644 --- a/http/Client.md +++ b/http/Client.md @@ -2,6 +2,12 @@ The HTTP client. See http\Client\Curl's [options](http/Client/Curl#Options:) which is the only driver currently supported. +## Changelog: + +Version | Change +--------|------- +2.3.0 | Deprecated methods:
http\Client::enablePipelining() and
http\Client::enableEvents().
Added Methods:
http\Client::configure(),
http\Client::getAvailableConfiguration() and
http\Client::getAvailableOptions(). + ## Examples: ### Sending a simple GET request: diff --git a/http/Client/Curl.md b/http/Client/Curl.md index 82b86ab..efd8d96 100644 --- a/http/Client/Curl.md +++ b/http/Client/Curl.md @@ -6,8 +6,9 @@ The http\Client\Curl namespace holds option value constants specific to the curl Version | Change --------|------- -2.1.0 | Added $dns_interface, $dns_local_ip4, $dns_local_ip6 options, $expect_100_timeout. -2.1.2 | Added request option constants:
http\Client\Curl::POSTREDIR_303,
http\Client\Curl::AUTH_SPNEGO,
http\Client\Curl::SSL_VERSION_TLSv1_0,
http\Client\Curl::SSL_VERSION_TLSv1_1 and
http\Client\Curl::SSL_VERSION_TLSv1_2 +2.1.0 | Added $dns_interface, $dns_local_ip4, $dns_local_ip6 and $expect_100_timeout options. +2.1.2 | Added request option constants:
http\Client\Curl\POSTREDIR_303,
http\Client\Curl\AUTH_SPNEGO,
http\Client\Curl\SSL_VERSION_TLSv1_0,
http\Client\Curl\SSL_VERSION_TLSv1_1 and
http\Client\Curl\SSL_VERSION_TLSv1_2 +2.3.0 | Added $pinned_publickey, $ltsauth and $verifystatus $ssl options.
Added $proxyheader and $unix_socket_path options.
Added request option constants:
http\Client\Curl\HTTP_VERSION_2_0 and
http\Client\Curl\TLS_AUTH_SRP. ## Constants: @@ -17,6 +18,8 @@ Version | Change Use HTTP/1.0 protocol version. * HTTP_VERSION_1_1 Use HTTP/1.1 protocol version. +* HTTP_VERSION_2_0 + Use HTTP/2 protocol version. Available if libcurl is v7.33.0 or more recent and was built with nghttp2 support. * HTTP_VERSION_ANY Use any HTTP protocol version. @@ -37,6 +40,11 @@ Version | Change * SSL_VERSION_ANY Use any encryption. +### TLS Auth Types + +* TLS_AUTH_SRP + 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. + ### DNS IP Version * IPRESOLVE_V4 @@ -96,31 +104,33 @@ The option names used here are more or less derived from the corresponding CURLO ### HTTP * int $protocol - The HTTP protocol version. See http\Client\Curl::HTTP_VERSION_* constants. + The HTTP protocol version. See http\Client\Curl\HTTP_VERSION_* constants. ### Proxies * string $proxyhost The hostname of the proxy. * int $proxytype - See http\Client\Curl::PROXY_* constants. + See http\Client\Curl\PROXY_* constants. * int $proxyport The port number of the proxy. * string $proxyauth user:password * int $proxyauthtype - See http\Client\Curl::AUTH_* constants. + See http\Client\Curl\AUTH_* constants. * bool $proxytunnel Tunnel all operations through the proxy. * string $noproxy Comma separated list of hosts where no proxy should be used. Available if libcurl is v7.19.4 or more recent. +* array $proxyheader + 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. ### DNS * int $dns_cache_timeout Resolved hosts will be kept fot this number of seconds. * int $ipresolve - See http\Client\Curl::IPRESOLVE_* constants. + See http\Client\Curl\IPRESOLVE_* constants. * array $resolve A list of HOST:PORT:ADDRESS mappings which pre-populate the DNS cache. Available if libcurl is v7.21.3 or more recent. * string $dns_servers @@ -166,13 +176,15 @@ The option names used here are more or less derived from the corresponding CURLO Interval in seconds to wait between sending keepalive probes. Available if libcurl is v7.25.0 or more recent. * bool $tcp_nodelay Disable [Nagle's algotrithm](http://tools.ietf.org/html/rfc896). - +* string $unix_socket_path + 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. + ### Authentication * string $httpauth user:password * int $httpauthtype - See http\Client\Curl::AUTH_* constants. + See http\Client\Curl\AUTH_* constants. ### Redirection @@ -181,7 +193,7 @@ The option names used here are more or less derived from the corresponding CURLO * bool $unrestricted_auth Whether to keep sending authentication credentials on redirects to different hosts. * int $postredir - See http\Client\Curl::POSTREDIR_* constants. Available if libcurl is v7.19.1 or more recent. + See http\Client\Curl\POSTREDIR_* constants. Available if libcurl is v7.19.1 or more recent. ### Retries @@ -249,7 +261,7 @@ The option names used here are more or less derived from the corresponding CURLO * string $engine Crypto engine to use for the private key. * int $version - See http\Client\Curl::SSL_VERSION_* constants. + See http\Client\Curl\SSL_VERSION_* constants. * bool $verifypeer Whether to apply peer verification. * bool $verifyhost @@ -270,3 +282,36 @@ The option names used here are more or less derived from the corresponding CURLO File with the concatenation of CRL in PEM format. Available if libcurl was built with OpenSSL support. * bool $certinfo Enable gathering of SSL certificate chain information. Available if libcurl is v7.19.1 or more recent. + * string $pinned_publickey + File with a public key to pin. Available if libcurl is v7.39.0 or more recent. + * int $tlsauthtype + TLS_AUTH_* constant. Available if libcurl is v7.21.4 or more recent. + * string $tlsauthuser + TLS-SRP username. Available if libcurl is v7.21.4 or more recent. + * string $lsauthpass + TLS-SRP password. Available if libcurl is v7.21.4 or more recent. + * bool $verifystatus + Enable OCSP. Available if libcurl is v7.41.0 or more recent and was build with openssl, gnutls or nss support. + +## Configuration: + +* int $maxconnects + Size of the connection cache. +* int $max_host_connections + Maximum number of connections to a single host. Available if libcurl is v7.30.0 or more recent. +* int $max_pipeline_length + Maximum number of requests in a pipeline. Available if libcurl is v7.30.0 or more recent. +* int $max_total_connections + Maximum number of simultaneous open connections of this client. Available if libcurl is v7.30.0 or more recent. +* bool $pipelining + Whether to enable HTTP/1.1 pipelining. +* int $chunk_length_penalty_size + Chunk length threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent. +* int $content_length_penalty_size + Size threshold for pipelining; no more requests on this pipeline if exceeded. Available if libcurl is v7.30.0 or more recent. +* array $pipelining_server_bl + Simple list of server software names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent. +* array $pipelining_site_bl + Simple list of server host names to blacklist for pipelining. Available if libcurl is v7.30.0 or more recent. +* bool $use_eventloop + Whether to use an event loop. Available if pecl/http was built with libevent support. diff --git a/http/Client/Request/addSslOptions.md b/http/Client/Request/addSslOptions.md index f11e35c..bb2eb6e 100644 --- a/http/Client/Request/addSslOptions.md +++ b/http/Client/Request/addSslOptions.md @@ -1,7 +1,7 @@ # http\Client\Request http\Client\Request::addSslOptions([array $ssl_options = NULL]) Add specific SSL options. -See http\Client\Request::setSslOptions(), http\Client\Request::setOptions() and http\Client\Curl::$ssl options. +See http\Client\Request::setSslOptions(), http\Client\Request::setOptions() and http\Client\Curl\$ssl options. ## Params: diff --git a/http/Client/Request/setSslOptions.md b/http/Client/Request/setSslOptions.md index 36bdcbc..c2d67e2 100644 --- a/http/Client/Request/setSslOptions.md +++ b/http/Client/Request/setSslOptions.md @@ -1,7 +1,7 @@ # http\Client\Request http\Client\Request::setSslOptions([array $ssl_options = NULL]) Specifically set SSL options. -See http\Client\Request::setOptions() and http\Client\Curl::$ssl options. +See http\Client\Request::setOptions() and http\Client\Curl\$ssl options. ## Params: diff --git a/http/Client/addSslOptions.md b/http/Client/addSslOptions.md index 639ae65..af3851c 100644 --- a/http/Client/addSslOptions.md +++ b/http/Client/addSslOptions.md @@ -1,7 +1,7 @@ # http\Client http\Client::addSslOptions([array $ssl_options = NULL]) Add specific SSL options. -See http\Client::setSslOptions(), http\Client::setOptions() and http\Client\Curl::$ssl options. +See http\Client::setSslOptions(), http\Client::setOptions() and http\Client\Curl\$ssl options. ## Params: diff --git a/http/Client/configure.md b/http/Client/configure.md new file mode 100644 index 0000000..21cca06 --- /dev/null +++ b/http/Client/configure.md @@ -0,0 +1,30 @@ +# http\Client http\Client::configure(array $configuration) + +Configure the client's low level options. + +## Params: + + * array $configuration + Key/value pairs of low level options. + See f.e. the [configuration options for the Curl driver](http/Client/Curl#Configuration:). + +## Returns: + +* http\Client, self. + +## Throws: + +* http\Exception\InvalidArgumentException +* http\Exception\UnexpectedValueException + +## Example: + + configure([ + "max_host_connections" => 8, + "pipelining" => true, + ]); + + ?> diff --git a/http/Client/enableEvents.md b/http/Client/enableEvents.md index 96bfd77..4411289 100644 --- a/http/Client/enableEvents.md +++ b/http/Client/enableEvents.md @@ -2,6 +2,9 @@ Enable usage of an event library like libevent, which might improve performance with big socket sets. +> ***NOTE:*** +> This method has been deprecated in 2.3.0, please use http\Client::configure() instead. + ## Params: * Optional bool $enable = true @@ -15,3 +18,9 @@ Enable usage of an event library like libevent, which might improve performance * http\Exception\InvalidArgumentException * http\Exception\UnexpectedValueException + +## Changelog: + +Version | Change +--------|------- +2.3.0 | This method has been deprecated. diff --git a/http/Client/enablePipelining.md b/http/Client/enablePipelining.md index 1f4c225..af8d82c 100644 --- a/http/Client/enablePipelining.md +++ b/http/Client/enablePipelining.md @@ -2,6 +2,9 @@ Enable sending pipelined requests to the same host if the driver supports it. +> ***NOTE:*** +> This method has been deprecated in 2.3.0, please use http\Client::configure() instead. + ## Params: * Optional bool $enable = true @@ -15,3 +18,9 @@ Enable sending pipelined requests to the same host if the driver supports it. * http\Exception\InvalidArgumentException * http\Exception\UnexpectedValueException + +## Changelog: + +Version | Change +--------|------- +2.3.0 | This method has been deprecated. diff --git a/http/Client/getAvailableConfiguration.md b/http/Client/getAvailableConfiguration.md new file mode 100644 index 0000000..d9d7c76 --- /dev/null +++ b/http/Client/getAvailableConfiguration.md @@ -0,0 +1,52 @@ +# array http\Client::getAvailableConfiguration() + +Get a list of available configuration options and their default values. + +See f.e. the [configuration options for the Curl driver](http/Client/Curl#Configuration:). + +## Params: + +None. + +## Returns: + +* array, list of key/value pairs of available configuarion options and their default values. + +## Throws: + +* http\Exception\InvalidArgumentException + +## Example: + + getAvailableConfiguration()); + + ?> + +Yields: + + array(10) { + ["maxconnects"]=> + int(-1) + ["max_host_connections"]=> + int(0) + ["max_pipeline_length"]=> + int(5) + ["max_total_connections"]=> + int(0) + ["pipelining"]=> + bool(false) + ["chunk_length_penalty_size"]=> + int(0) + ["content_length_penalty_size"]=> + int(0) + ["pipelining_server_bl"]=> + NULL + ["pipelining_site_bl"]=> + NULL + ["use_eventloop"]=> + bool(false) + } + diff --git a/http/Client/getAvailableOptions.md b/http/Client/getAvailableOptions.md new file mode 100644 index 0000000..fbb6c83 --- /dev/null +++ b/http/Client/getAvailableOptions.md @@ -0,0 +1,179 @@ +# array http\Client::getAvailableOptions() + +Retrieve a list of available request options and their default values. + +See f.e. the [request options for the Curl driver](http/Client/Curl#Options:). + +## Params: + +None. + +## Returns: + +* array, list of key/value pairs of available request options and their default values. + +## Throws: + +* http\Exception\InvalidArgumentException + +## Example: + + getAvailableOptions()); + + ?> + +Yields: + + array(49) { + ["proxyhost"]=> + NULL + ["proxytype"]=> + int(0) + ["proxyport"]=> + int(0) + ["proxyauth"]=> + NULL + ["proxyauthtype"]=> + int(-18) + ["proxytunnel"]=> + bool(false) + ["noproxy"]=> + NULL + ["proxyheader"]=> + NULL + ["unix_socket_path"]=> + NULL + ["dns_cache_timeout"]=> + int(60) + ["ipresolve"]=> + int(0) + ["resolve"]=> + NULL + ["low_speed_limit"]=> + int(0) + ["low_speed_time"]=> + int(0) + ["fresh_connect"]=> + bool(false) + ["forbid_reuse"]=> + bool(false) + ["interface"]=> + NULL + ["portrange"]=> + NULL + ["port"]=> + int(0) + ["address_scope"]=> + int(0) + ["httpauth"]=> + NULL + ["httpauthtype"]=> + int(-18) + ["redirect"]=> + int(0) + ["unrestricted_auth"]=> + bool(false) + ["postredir"]=> + int(0) + ["retrycount"]=> + int(0) + ["retrydelay"]=> + float(0) + ["referer"]=> + NULL + ["autoreferer"]=> + bool(true) + ["useragent"]=> + string(51) "PECL_HTTP/2.3.0dev PHP/5.6.6-dev libcurl/7.41.0-DEV" + ["resume"]=> + int(0) + ["range"]=> + NULL + ["etag"]=> + NULL + ["compress"]=> + bool(false) + ["lastmodified"]=> + int(0) + ["encodecookies"]=> + bool(true) + ["cookies"]=> + NULL + ["cookiesession"]=> + bool(false) + ["cookiestore"]=> + NULL + ["maxfilesize"]=> + int(0) + ["protocol"]=> + int(0) + ["timeout"]=> + float(0) + ["connecttimeout"]=> + float(3) + ["expect_100_timeout"]=> + float(1) + ["tcp_nodelay"]=> + bool(false) + ["tcp_keepalive"]=> + bool(false) + ["tcp_keepidle"]=> + int(60) + ["tcp_keepintvl"]=> + int(60) + ["ssl"]=> + array(24) { + ["cert"]=> + NULL + ["certtype"]=> + string(3) "PEM" + ["key"]=> + NULL + ["keytype"]=> + string(3) "PEM" + ["keypasswd"]=> + NULL + ["engine"]=> + NULL + ["version"]=> + int(0) + ["verifypeer"]=> + bool(true) + ["verifyhost"]=> + bool(true) + ["verifystatus"]=> + bool(false) + ["cipher_list"]=> + NULL + ["cainfo"]=> + string(34) "/etc/ssl/certs/ca-certificates.crt" + ["capath"]=> + NULL + ["random_file"]=> + NULL + ["egdsocket"]=> + NULL + ["issuercert"]=> + NULL + ["crlfile"]=> + NULL + ["certinfo"]=> + bool(false) + ["enable_npn"]=> + bool(true) + ["enable_alpn"]=> + bool(true) + ["pinned_publickey"]=> + NULL + ["tlsauthtype"]=> + int(0) + ["tlsauthuser"]=> + NULL + ["tlsauthpass"]=> + NULL + } + } + diff --git a/http/Client/getTransferInfo.md b/http/Client/getTransferInfo.md index a644ea7..d8ad5d5 100644 --- a/http/Client/getTransferInfo.md +++ b/http/Client/getTransferInfo.md @@ -80,9 +80,6 @@ The transfer info might look as follows: [2]=> string(7) "dynamic" } - ["cookies"]=> - array(0) { - } ["redirect_url"]=> string(15) "http://php.net/" ["primary_ip"]=> diff --git a/http/Client/setSslOptions.md b/http/Client/setSslOptions.md index 9304c37..df216e3 100644 --- a/http/Client/setSslOptions.md +++ b/http/Client/setSslOptions.md @@ -1,7 +1,7 @@ # http\Client http\Client::setSslOptions([array $ssl_options = NULL]) Specifically set SSL options. -See http\Client::setOptions() and http\Client\Curl::$ssl options. +See http\Client::setOptions() and http\Client\Curl\$ssl options. ## Params: -- 2.30.2