From bea65a44c88e5b048152cec8eb25d217e4442a57 Mon Sep 17 00:00:00 2001 From: Michael Wallner Date: Thu, 18 Aug 2016 22:28:16 +0200 Subject: [PATCH] flush docs --- http.md | 11 +-- http/Client.md | 118 +++--------------------- http/Client/: Changelog.md | 20 +++++ http/Client/: Examples.md | 97 ++++++++++++++++++++ http/Client/Curl.md | 36 +++++--- http/Client/Curl/: Changelog.md | 51 +++++++++++ http/Client/Curl/Features.md | 45 ++++++++++ http/Client/Curl/User.md | 19 ++++ http/Client/Curl/User/: Examples.md | 112 +++++++++++++++++++++++ http/Client/Curl/User/init.md | 13 +++ http/Client/Curl/User/once.md | 11 +++ http/Client/Curl/User/send.md | 10 +++ http/Client/Curl/User/socket.md | 10 +++ http/Client/Curl/User/timer.md | 8 ++ http/Client/Curl/User/wait.md | 11 +++ http/Client/Curl/Versions.md | 19 ++++ http/Client/configure.md | 3 + http/Client/enableEvents.md | 6 -- http/Client/enablePipelining.md | 6 -- http/Client/setDebug.md | 124 ++++++++++++++++++++++++++ http/Env.md | 13 --- http/Env/: Changelog.md | 12 +++ http/Env/Request.md | 6 -- http/Env/Request/: Changelog.md | 7 ++ http/Env/Response.md | 6 -- http/Env/Response/: Changelog.md | 7 ++ http/Env/Url.md | 8 ++ http/Header/Parser.md | 7 +- http/Message.md | 1 + http/Message/Parser.md | 7 +- http/Message/addHeaders.md | 7 +- http/Message/setHeader.md | 10 +++ http/Message/setHeaders.md | 9 ++ http/Params.md | 133 ---------------------------- http/Params/: Changelog.md | 8 ++ http/Params/: Examples.md | 127 ++++++++++++++++++++++++++ http/Url.md | 14 --- http/Url/: Changelog.md | 20 +++++ http/Url/__construct.md | 13 ++- http/Url/mod.md | 8 +- 40 files changed, 828 insertions(+), 325 deletions(-) create mode 100644 http/Client/: Changelog.md create mode 100644 http/Client/: Examples.md create mode 100644 http/Client/Curl/: Changelog.md create mode 100644 http/Client/Curl/Features.md create mode 100644 http/Client/Curl/User.md create mode 100644 http/Client/Curl/User/: Examples.md create mode 100644 http/Client/Curl/User/init.md create mode 100644 http/Client/Curl/User/once.md create mode 100644 http/Client/Curl/User/send.md create mode 100644 http/Client/Curl/User/socket.md create mode 100644 http/Client/Curl/User/timer.md create mode 100644 http/Client/Curl/User/wait.md create mode 100644 http/Client/Curl/Versions.md create mode 100644 http/Client/setDebug.md create mode 100644 http/Env/: Changelog.md create mode 100644 http/Env/Request/: Changelog.md create mode 100644 http/Env/Response/: Changelog.md create mode 100644 http/Env/Url.md create mode 100644 http/Params/: Changelog.md create mode 100644 http/Params/: Examples.md create mode 100644 http/Url/: Changelog.md diff --git a/http.md b/http.md index 0d483fa..d70403e 100644 --- a/http.md +++ b/http.md @@ -115,8 +115,9 @@ The http extension registers the ```http.*``` namespace for its stream filters. ## Changelog: -Version | Change ---------|------- -2.0.4 | Dropped the pecl/event conflict. -2.4.0 | Dropped the ext/json dependency. -2.4.2 | Added libidn2 and libicu as fallback for IDNA support. +0. v2.0.4 + * Dropped the pecl/event conflict. +0. v2.4.0 + * Dropped the ext/json dependency. +0. v2.4.2 + * Added libidn2 and libicu as fallback for IDNA support. diff --git a/http/Client.md b/http/Client.md index 14626a7..ba66dc0 100644 --- a/http/Client.md +++ b/http/Client.md @@ -2,110 +2,20 @@ 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: - - "My Client/0.1"] - ); - $request->setOptions(["timeout"=>1]); - - $client = new http\Client; - $client->enqueue($request)->send(); - - // pop the last retrieved response - $response = $client->getResponse(); - printf("%s returned '%s' (%d)\n", - $response->getTransferInfo("effective_url"), - $response->getInfo(), - $response->getResponseCode() - ); - ?> - -#### Yields: - - http://localhost/ returned 'HTTP/1.1 200 OK' (200) - - -### Submitting a standard form: - - "application/x-www-form-urlencoded"] - ); - $request->getBody()->append(new http\QueryString([ - "user" => "mike", - "name" => "Michael Wallner" - ])); - - $client = new http\Client; - $client->setOptions(["ssl" => [ - "version" => http\Client\Curl\SSL_VERSION_TLSv1 - ]]); - $client->enqueue($request)->send(); - - // ask for the response for this specific request - $response = $client->getResponse($request); - printf("-> %s\n", $response->getInfo()); - - ?> - -#### Yields: - - -> HTTP/1.1 200 OK - - -### Submitting a multipart form: - - getBody()->addForm([ - "user" => "mike", - "name" => "Michael Wallner" - ], [ - [ - "name" => "image", - "type" => "image/jpeg", - "file" => "image.jpg" - ] - ]); - - $client = new http\Client; - $client->setOptions(["ssl" => [ - "version" => http\Client\Curl\SSL_VERSION_TLSv1 - ]]); - $client->enqueue($request)->send(); - - // ask for the response for this specific request - $response = $client->getResponse($request); - printf("-> %.2F kB\n @ %.2F Mbit", - .001 * $response->getTransferInfo("size_upload"), - .0000008 * $response->getTransferInfo("speed_upload") - ); - ?> - -#### Yields: - - -> 15.98 kB @ 6.77 Mbit - +## Constants: + +* DEBUG_INFO + Debug callback's $data contains human readable text. +* DEBUG_IN + Debug callback's $data contains data received. +* DEBUG_OUT + Debug callback's $data contains data sent. +* DEBUG_HEADER + Debug callback's $data contains headers. +* DEBUG_BODY + Debug callback's $data contains a body part. +* DEBUG_SSL + Debug callback's $data contains SSL data. ## Properties: diff --git a/http/Client/: Changelog.md b/http/Client/: Changelog.md new file mode 100644 index 0000000..1f9c3d5 --- /dev/null +++ b/http/Client/: Changelog.md @@ -0,0 +1,20 @@ +# http\Client Changelog + +0. v2.3.0 + * Deprecated methods: + * http\Client::enablePipelining() + * http\Client::enableEvents() + * Added methods: + * http\Client::configure() + * http\Client::getAvailableConfiguration() + * http\Client::getAvailableOptions() +0. v2.6.0, v3.1.0 + * Added methods: + * http\Client::setDebug() + * Added constants: + * http\Client::DEBUG_INFO + * http\Client::DEBUG_IN + * http\Client::DEBUG_OUT + * http\Client::DEBUG_HEADER + * http\Client::DEBUG_BODY + * http\Client::DEBUG_SSL diff --git a/http/Client/: Examples.md b/http/Client/: Examples.md new file mode 100644 index 0000000..23d4593 --- /dev/null +++ b/http/Client/: Examples.md @@ -0,0 +1,97 @@ +# http\Client Examples + +## Sending a simple GET request: + + "My Client/0.1"] + ); + $request->setOptions(["timeout"=>1]); + + $client = new http\Client; + $client->enqueue($request)->send(); + + // pop the last retrieved response + $response = $client->getResponse(); + printf("%s returned '%s' (%d)\n", + $response->getTransferInfo("effective_url"), + $response->getInfo(), + $response->getResponseCode() + ); + ?> + +### Yields: + + http://localhost/ returned 'HTTP/1.1 200 OK' (200) + + +## Submitting a standard form: + + "application/x-www-form-urlencoded"] + ); + $request->getBody()->append(new http\QueryString([ + "user" => "mike", + "name" => "Michael Wallner" + ])); + + $client = new http\Client; + $client->setOptions(["ssl" => [ + "version" => http\Client\Curl\SSL_VERSION_TLSv1 + ]]); + $client->enqueue($request)->send(); + + // ask for the response for this specific request + $response = $client->getResponse($request); + printf("-> %s\n", $response->getInfo()); + + ?> + +### Yields: + + -> HTTP/1.1 200 OK + + +## Submitting a multipart form: + + getBody()->addForm([ + "user" => "mike", + "name" => "Michael Wallner" + ], [ + [ + "name" => "image", + "type" => "image/jpeg", + "file" => "image.jpg" + ] + ]); + + $client = new http\Client; + $client->setOptions(["ssl" => [ + "version" => http\Client\Curl\SSL_VERSION_TLSv1 + ]]); + $client->enqueue($request)->send(); + + // ask for the response for this specific request + $response = $client->getResponse($request); + printf("-> %.2F kB\n @ %.2F Mbit", + .001 * $response->getTransferInfo("size_upload"), + .0000008 * $response->getTransferInfo("speed_upload") + ); + ?> + +### Yields: + + -> 15.98 kB @ 6.77 Mbit diff --git a/http/Client/Curl.md b/http/Client/Curl.md index afc578c..12fc7f9 100644 --- a/http/Client/Curl.md +++ b/http/Client/Curl.md @@ -2,15 +2,17 @@ The http\Client\Curl namespace holds option value constants specific to the curl driver of the http\Client. -## Changelog +## Constants: -Version | Change ---------|------- -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. +### Features and Versions: -## Constants: +* FEATURES + Bitmask of available libcurl features. + See http\Client\Curl\Features namespace. +* VERSIONS + List of library versions of or linked into libcurl, + e.g. "libcurl/7.50.0 OpenSSL/1.0.2h zlib/1.2.8 libidn/1.32 nghttp2/1.12.0". + See http\Client\Curl\Versions namespace. ### HTTP Protocol Version @@ -124,6 +126,8 @@ The option names used here are more or less derived from the corresponding CURLO 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. +* string $proxy_service_name + 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. ### DNS @@ -178,6 +182,8 @@ The option names used here are more or less derived from the corresponding CURLO 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. +* bool $path_as_is + Do *not* squash sequences of "/../" or "/./" that may exist in the URL's path. ### Authentication @@ -185,6 +191,8 @@ The option names used here are more or less derived from the corresponding CURLO user:password * int $httpauthtype See http\Client\Curl\AUTH_* constants. +* string $service_name + 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. ### Redirection @@ -291,7 +299,9 @@ The option names used here are more or less derived from the corresponding CURLO * 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. + Enable OCSP. Available if libcurl is v7.41.0 or more recent and was built with OpenSSL, GnuTLS or NSS support. + * bool $falsestart + 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. ## Configuration: @@ -313,5 +323,11 @@ The option names used here are more or less derived from the corresponding CURLO 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. +* mixed $use_eventloop + Whether to use an event loop. This option accepts either bool, whether to use + the internal event loop, or an instance of an http\Client\Curl\User implementation. + The internal event loop is only available if pecl/http was built with libevent support. +* bool $share_cookies + Whether to let the client share cookies between requests. +* bool $share_ssl + Whether to let the client share SSL/TLS sessions between requests. Available if libcurl is v7.23.0 or more recent. diff --git a/http/Client/Curl/: Changelog.md b/http/Client/Curl/: Changelog.md new file mode 100644 index 0000000..457079b --- /dev/null +++ b/http/Client/Curl/: Changelog.md @@ -0,0 +1,51 @@ +# http\Client\Curl Changelog + +0. v2.1.0 + * Added request options: + * $dns_interface + * $dns_local_ip4 + * $dns_local_ip6 + * $expect_100_timeout +0. v2.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 + * http\Client\Curl\SSL_VERSION_TLSv1_2 +0. v2.3.0 + * Added request options: + * $proxyheader + * $unix_socket_path + * Added SSL request options: + * $pinned_publickey + * $tlsauth + * $verifystatus + * Added request option constants: + * http\Client\Curl\HTTP_VERSION_2_0 + * http\Client\Curl\TLS_AUTH_SRP +0. v2.5.1 + * Added request options: + * $proxy_service_name + * $service_name + * Added SSL request options: + * $falsestart +0. v2.5.6 + * Added request option constants: + * http\Client\Curl\HTTP_VERSION_2TLS +0. v2.6.0, v3.1.0 + * Added methods: + * http\Client::setDebug() + * Added client configure options: + * $share_cookies + * $share_ssl + * Changed client configure options: + * bool $use_eventloop changed to mixed to accept an http\Client\Curl\User implementation + * Added constants: + * http\Client\Curl::FEATURES + * http\Client\Curl::VERSIONS + * Added namespaces: + * http\Client\Curl\Features + * http\Client\Curl\Versions + * Added interfaces: + * http\Client\Curl\User diff --git a/http/Client/Curl/Features.md b/http/Client/Curl/Features.md new file mode 100644 index 0000000..06fbd85 --- /dev/null +++ b/http/Client/Curl/Features.md @@ -0,0 +1,45 @@ +# namespace http\Client\Curl\Features + +CURL feature constants. + +> ***NOTE:*** +> These constants have been added in v2.6.0, resp. v3.1.0. + +## Constants: + +* ASYNCHDNS + Whether libcurl supports asynchronous domain name resolution. +* GSSAPI + Whether libcurl supports the Generic Security Services Application Program Interface. Available if libcurl is v7.38.0 or more recent. +* GSSNEGOTIATE + Whether libcurl supports HTTP Generic Security Services negotiation. +* HTTP2 + Whether libcurl supports the HTTP/2 protocol. Available if libcurl is v7.33.0 or more recent. +* IDN + Whether libcurl supports international domain names. +* IPV6 + Whether libcurl supports IPv6. +* KERBEROS4 + Whether libcurl supports the old Kerberos protocol. +* KERBEROS5 + Whether libcurl supports the more recent Kerberos v5 protocol. Available if libcurl is v7.40.0 or more recent. +* LARGEFILE + Whether libcurl supports large files. +* LIBZ + Whether libcurl supports gzip/deflate compression. +* NTLM + Whether libcurl supports the NT Lan Manager authentication. +* NTLM_WB + Whether libcurl supports NTLM delegation to a winbind helper. Available if libcurl is v7.22.0 or more recent. +* PSL + Whether libcurl supports the Public Suffix List for cookie host handling. Available if libcurl is v7.47.0 or more recent. +* SPNEGO + Whether libcurl supports the Simple and Protected GSSAPI Negotiation Mechanism. +* SSL + Whether libcurl supports SSL/TLS protocols. +* SSPI + Whether libcurl supports the Security Support Provider Interface. +* TLSAUTH_SRP + Whether libcurl supports TLS Secure Remote Password authentication. Available if libcurl is v7.21.4 or more recent. +* UNIX_SOCKETS + Whether libcurl supports connections to unix sockets. Available if libcurl is v7.40.0 or more recent. diff --git a/http/Client/Curl/User.md b/http/Client/Curl/User.md new file mode 100644 index 0000000..7eb455b --- /dev/null +++ b/http/Client/Curl/User.md @@ -0,0 +1,19 @@ +# interface http\Client\Curl\User + +Interface to an user event loop implementation for http\Client::configure()'s $use_eventloop option. + +> ***NOTE:*** +> This interface was added in v2.6.0, resp. v3.1.0. + +## Constants: + +* POLL_NONE + No action. +* POLL_IN + Poll for read readiness. +* POLL_OUT + Poll for write readiness. +* POLL_INOUT + Poll for read/write readiness. +* POLL_REMOVE + Stop polling for activity on this descriptor. diff --git a/http/Client/Curl/User/: Examples.md b/http/Client/Curl/User/: Examples.md new file mode 100644 index 0000000..4c732c7 --- /dev/null +++ b/http/Client/Curl/User/: Examples.md @@ -0,0 +1,112 @@ +# http\Client\Curl\User Examples + +## Example using the [pecl/ev](http://pecl.php.net/ev) loop: + + client = $client; + } + + function init(callable $run) { + $this->run = $run; + } + + function timer(int $timeout_ms) { + echo "T"; + if (isset($this->timeout)) { + $this->timeout->set($timeout_ms/1000, 0); + $this->timeout->start(); + } else { + $this->timeout = new EvTimer($timeout_ms/1000, 0, function() { + if (!call_user_func($this->run, $this->client)) { + if ($this->timeout) { + $this->timeout->stop(); + $this->timeout = null; + } + } + }); + } + } + + function socket($socket, int $action) { + echo "S"; + + switch ($action) { + case self::POLL_NONE: + break; + case self::POLL_REMOVE: + if (isset($this->ios[(int) $socket])) { + echo "U"; + $this->ios[(int) $socket]->stop(); + unset($this->ios[(int) $socket]); + } + break; + + default: + $ev = 0; + if ($action & self::POLL_IN) { + $ev |= Ev::READ; + } + if ($action & self::POLL_OUT) { + $ev |= Ev::WRITE; + } + if (isset($this->ios[(int) $socket])) { + $this->ios[(int) $socket]->set($socket, $ev); + } else { + $this->ios[(int) $socket] = new EvIo($socket, $ev, function($watcher, $events) use($socket) { + $action = 0; + if ($events & Ev::READ) { + $action |= self::POLL_IN; + } + if ($events & Ev::WRITE) { + $action |= self::POLL_OUT; + } + if (!call_user_func($this->run, $this->client, $socket, $action)) { + if ($this->timeout) { + $this->timeout->stop(); + $this->timeout = null; + } + } + }); + } + break; + } + } + + function once() { + throw new BadMethodCallException("this example uses Ev::run()"); + } + + function wait(int $timeout_ms = null) { + throw new BadMethodCallException("this example uses Ev::run()"); + } + + function send() { + throw new BadMethodCallException("this example uses Ev::run()"); + } + } + + $client = new http\Client; + $client->configure([ + "use_eventloop" => new UserHandler($client) + ]); + $client->enqueue(new http\Client\Request("GET", "http://example.com/"), function($r) { + var_dump($r->getResponseCode()); + }); + + Ev::run(); + + ?> + +### Yields: + + TTTTTTTTSTSTSUint(200) diff --git a/http/Client/Curl/User/init.md b/http/Client/Curl/User/init.md new file mode 100644 index 0000000..45afb55 --- /dev/null +++ b/http/Client/Curl/User/init.md @@ -0,0 +1,13 @@ +# void http\Client\Curl\User::init(callable $run) + +Initialize the event loop. + + +## Params: + +* callable $run as function(http\Client $c, resource $s = null, int $action = http\Client\Curl\User::POLL_NONE) : int + Internal callback returning the number of unfinished requests pending. + + +> ***NOTE***: +> The callback should be run when a timeout occurs or a watched socket needs action. diff --git a/http/Client/Curl/User/once.md b/http/Client/Curl/User/once.md new file mode 100644 index 0000000..0c3aa58 --- /dev/null +++ b/http/Client/Curl/User/once.md @@ -0,0 +1,11 @@ +# void http\Client\Curl\User::once() + +Run the loop as long as it does not block. + +> ***NOTE:*** +> This method is called by http\Client::once(), so it does not need to have an actual implementation if http\Client::once() is never called. + + +## Params: + +None. diff --git a/http/Client/Curl/User/send.md b/http/Client/Curl/User/send.md new file mode 100644 index 0000000..9bd3c35 --- /dev/null +++ b/http/Client/Curl/User/send.md @@ -0,0 +1,10 @@ +# void http\Client\Curl\User::send() + +Run the loop. + +> ***NOTE:*** +> This method is called by http\Client::send(), so it does not need to have an actual implementation if http\Client::send() is never called. + +## Params: + +None. diff --git a/http/Client/Curl/User/socket.md b/http/Client/Curl/User/socket.md new file mode 100644 index 0000000..4ef660d --- /dev/null +++ b/http/Client/Curl/User/socket.md @@ -0,0 +1,10 @@ +# void http\Client\Curl\User::socket(resource $socket, int $poll) + +Register (or deregister) a socket watcher. + +## Params: + +* resource $socket + The socket descriptor to watch. +* int $poll + http\Client\Curl\User::POLL_* constant. diff --git a/http/Client/Curl/User/timer.md b/http/Client/Curl/User/timer.md new file mode 100644 index 0000000..2205799 --- /dev/null +++ b/http/Client/Curl/User/timer.md @@ -0,0 +1,8 @@ +# void http\Client\Curl\User::timer(int $timeout_ms) + +Register a timeout watcher. + +## Params: + +* int $timeout_ms + Desired maximum timeout in milliseconds. diff --git a/http/Client/Curl/User/wait.md b/http/Client/Curl/User/wait.md new file mode 100644 index 0000000..06ee274 --- /dev/null +++ b/http/Client/Curl/User/wait.md @@ -0,0 +1,11 @@ +# void http\Client\Curl\User::wait([int $timeout_ms = null]) + +Wait/poll/select (block the loop) until events fire. + +> ***NOTE:*** +> This method is called by http\Client::wait(), so it does not need to have an actual implementation if http\Client::wait() is never called. + +## Params: + +* Optional int $timeout_ms = null + Block for at most this milliseconds. diff --git a/http/Client/Curl/Versions.md b/http/Client/Curl/Versions.md new file mode 100644 index 0000000..794fe2e --- /dev/null +++ b/http/Client/Curl/Versions.md @@ -0,0 +1,19 @@ +# namespace http\Client\Curl\Versions + +CURL version constants. + +> ***NOTE:*** +> These constants have been added in v2.6.0, resp. v3.1.0. + +## Constants: + +* CURL + Version string of libcurl, e.g. "7.50.0". +* SSL + Version string of the SSL/TLS library, e.g. "OpenSSL/1.0.2h". +* LIBZ + Version string of the zlib compression library, e.g. "1.2.8". +* ARES + Version string of the c-ares library, e.g. "1.11.0". +* IDN + Version string of the IDN library, e.g. "1.32". diff --git a/http/Client/configure.md b/http/Client/configure.md index 21cca06..7d88630 100644 --- a/http/Client/configure.md +++ b/http/Client/configure.md @@ -2,6 +2,9 @@ Configure the client's low level options. +> ***NOTE:*** +> This method has been added in v2.3.0. + ## Params: * array $configuration diff --git a/http/Client/enableEvents.md b/http/Client/enableEvents.md index 4411289..369bfa6 100644 --- a/http/Client/enableEvents.md +++ b/http/Client/enableEvents.md @@ -18,9 +18,3 @@ 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 af8d82c..221713d 100644 --- a/http/Client/enablePipelining.md +++ b/http/Client/enablePipelining.md @@ -18,9 +18,3 @@ 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/setDebug.md b/http/Client/setDebug.md new file mode 100644 index 0000000..9ca4ba8 --- /dev/null +++ b/http/Client/setDebug.md @@ -0,0 +1,124 @@ +# http\Client http\Client::setDebug(callable $callback) + +Set client debugging callback. + +> ***NOTE:*** +> This method has been added in v2.6.0, resp. v3.1.0. + +## Params: + +* callable $callback as function(http\Client $c, http\Client\Request $r, int $type, string $data) + The debug callback. For $type see http\Client::DEBUG_* constants. + +## Returns: + +* http\Client, self. + +## Throws: + +* http\Exception\InvalidArgumentException + +## Example: + + setDebug(function($c, $r, $type, $data) { + if ($type === http\Client::DEBUG_INFO) { + printf("INFO: %s\n", $data); + } else { + repeat: + if ($type & http\Client::DEBUG_OUT) { + $sep = ">"; + } elseif ($type & http\Client::DEBUG_IN) { + $sep = "<"; + } + if ($type & http\Client::DEBUG_SSL) { + printf("%s <%d bytes of SSL data>\n", $sep, strlen($data)); + } else { + printf("%s %s\n", $sep, str_replace("\n", "\n$sep ", rtrim($data, "\n"))); + } + } + })->enqueue(new http\Client\Request("GET", "http://example.com"))->send(); + + ?> + +> ***NOTE:*** +> Except for http\Client::DEBUG_INFO, which always occurs separately, the debug +> callback's $type argument contains a bitmask of (http\Client::DEBUG_IN or http\Client::DEBUG_OUT) +> and (http\Client::DEBUG_HEADER or http\Client::DEBUG_BODY or http\Client::DEBUG_SSL). + +### Yields: + + INFO: Trying 93.184.216.34... + + INFO: Connected to example.com (93.184.216.34) port 80 (#0) + + > GET / HTTP/1.1 + > Host: example.com + > User-Agent: PECL_HTTP/2.6.0dev PHP/5.6.19RC1 libcurl/7.50.0-DEV + > Accept: */* + > + < HTTP/1.1 200 OK + < Cache-Control: max-age=604800 + < Content-Type: text/html + < Date: Thu, 18 Aug 2016 17:55:10 GMT + < Etag: "359670651+gzip+ident" + < Expires: Thu, 25 Aug 2016 17:55:10 GMT + < Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT + < Server: ECS (iad/182A) + < Vary: Accept-Encoding + < X-Cache: HIT + < x-ec-custom-error: 1 + < Content-Length: 1270 + < + < + < + < + < Example Domain + < + < + < + < + < + < + < + < + <
+ <

Example Domain

+ <

This domain is established to be used for illustrative examples in documents. You may use this + < domain in examples without prior coordination or asking for permission.

+ <

More information...

+ <
+ < + < + INFO: Connection #0 to host example.com left intact diff --git a/http/Env.md b/http/Env.md index 255c81a..f695c19 100644 --- a/http/Env.md +++ b/http/Env.md @@ -1,16 +1,3 @@ # class http\Env The http\Env class provides static methods to manipulate and inspect the server's current request's HTTP environment. - -## Changelog: - -| Version | Change -|---------|-------- -| 2.4.0 | Split off pecl/[apfd](apfd) and pecl/[json_post](json_post) - -## Request startup - -In versions lower than 2.4.0, the http\Env module extends PHP's builtin POST data parser to be run also if the request method is not POST. Additionally it will handle application/json payloads if ext/json is available. Successfully parsed JSON will be put right into the $_POST array. - -This functionality has been separated into two distict extensions, pecl/[apfd](apfd) and pecl/[json_post](json_post). - diff --git a/http/Env/: Changelog.md b/http/Env/: Changelog.md new file mode 100644 index 0000000..2b10e4a --- /dev/null +++ b/http/Env/: Changelog.md @@ -0,0 +1,12 @@ +# http\Env Changelog + +0. v2.4.0 + * Split off pecl/[apfd](apfd) and pecl/[json_post](json_post) + +## Backwards compatibility notes + +### Request startup prior v2.4.0 + +In versions lower than 2.4.0, the http\Env module extends PHP's builtin POST data parser to be run also if the request method is not POST. Additionally it will handle application/json payloads if ext/json is available. Successfully parsed JSON will be put right into the $_POST array. + +This functionality has been separated into two distict extensions, pecl/[apfd](apfd) and pecl/[json_post](json_post). diff --git a/http/Env/Request.md b/http/Env/Request.md index 6aef6c7..ad9ebc2 100644 --- a/http/Env/Request.md +++ b/http/Env/Request.md @@ -4,12 +4,6 @@ The http\Env\Request class' instances represent the server's current HTTP reques See http\Message for inherited members. -## Changelog: - -Version | Changes ---------|-------- -2.2.0 | Added http\Env\Request::getCookie() and http\Env\Request::$cookie. - ## Constants: None. diff --git a/http/Env/Request/: Changelog.md b/http/Env/Request/: Changelog.md new file mode 100644 index 0000000..39f7489 --- /dev/null +++ b/http/Env/Request/: Changelog.md @@ -0,0 +1,7 @@ +# http\Env\Request Changelog + +0. v2.2.0 + * Added methods: + * http\Env\Request::getCookie() + * Added properties: + * http\Env\Request::$cookie diff --git a/http/Env/Response.md b/http/Env/Response.md index 2b36921..187005c 100644 --- a/http/Env/Response.md +++ b/http/Env/Response.md @@ -4,12 +4,6 @@ The http\Env\Response class' instances represent the server's current HTTP respo See http\Message for inherited members. -## Changelog: - -Version | Changes ---------|-------- -2.2.0 | Added http\Env\Response::setCookie() and http\Env\Response::$cookies. - ## Constants: * CONTENT_ENCODING_NONE diff --git a/http/Env/Response/: Changelog.md b/http/Env/Response/: Changelog.md new file mode 100644 index 0000000..0a7ceab --- /dev/null +++ b/http/Env/Response/: Changelog.md @@ -0,0 +1,7 @@ +# http\Env\Response Changelog + +0. v2.2.0 + * Added methods: + * http\Env\Response::setCookie() + * Added properties: + * http\Env\Response::$cookies diff --git a/http/Env/Url.md b/http/Env/Url.md new file mode 100644 index 0000000..86e20c0 --- /dev/null +++ b/http/Env/Url.md @@ -0,0 +1,8 @@ +# class http\Env\Url extends http\Url + +URL class using the HTTP environment by default. + +> ***NOTE:*** +> This class has been added in v3.0.0. + +Always adds http\Url::FROM_ENV to the $flags constructor argument. See also http\Url. diff --git a/http/Header/Parser.md b/http/Header/Parser.md index 76f4eaf..598043f 100644 --- a/http/Header/Parser.md +++ b/http/Header/Parser.md @@ -2,11 +2,8 @@ The parser which is underlying http\Header and http\Message. -## Changelog: - -| Version | Change -|---------|-------- -| 2.3.0 | Added http\Header\Parser API +> ***NOTE:*** +> This class has been added in v2.3.0. ## Constants: diff --git a/http/Message.md b/http/Message.md index ca48ff2..c7ef74b 100644 --- a/http/Message.md +++ b/http/Message.md @@ -1,6 +1,7 @@ # class http\Message implements Countable, Serializable, Iterator The message class builds the foundation for any request and response message. + See http\Client\Request and http\Client\Response, as well as http\Env\Request and http\Env\Response. ## Constants: diff --git a/http/Message/Parser.md b/http/Message/Parser.md index bd70220..416fedb 100644 --- a/http/Message/Parser.md +++ b/http/Message/Parser.md @@ -2,11 +2,8 @@ The parser which is underlying http\Message. -## Changelog: - -| Version | Change -|---------|-------- -| 2.2.0 | Added http\Message\Parser API +> ***NOTE:**** +> This class was added in v2.2.0. ## Constants: diff --git a/http/Message/addHeaders.md b/http/Message/addHeaders.md index 168803a..645ae09 100644 --- a/http/Message/addHeaders.md +++ b/http/Message/addHeaders.md @@ -43,12 +43,7 @@ Yields: } array(1) { ["Cache-Control"]=> - array(2) { - [0]=> - string(7) "private" - [1]=> - string(15) "must-revalidate" - } + string(24) "private, must-revalidate" } Cache-Control: private, must-revalidate diff --git a/http/Message/setHeader.md b/http/Message/setHeader.md index e5fa062..98f5847 100644 --- a/http/Message/setHeader.md +++ b/http/Message/setHeader.md @@ -3,6 +3,10 @@ Set a single header. See http\Message::getHeader() and http\Message::addHeader(). +> **NOTE:** +> Prior to v2.5.6/v3.1.0 headers with the same name were merged into a single +> header with values concatenated by comma. + ## Params: * string $header @@ -13,3 +17,9 @@ See http\Message::getHeader() and http\Message::addHeader(). ## Returns: * http\Message, self. + +## Changelog: + +Version | Changes +-------------|-------- +2.5.6, 3.1.0 | Multiple headers with the same name are kept separate instead of merged together. diff --git a/http/Message/setHeaders.md b/http/Message/setHeaders.md index 875d49e..2ce4418 100644 --- a/http/Message/setHeaders.md +++ b/http/Message/setHeaders.md @@ -3,6 +3,10 @@ Set the message headers. See http\Message::getHeaders() and http\Message::addHeaders(). +> **NOTE:** +> Prior to v2.5.6/v3.1.0 headers with the same name were merged into a single +> header with values concatenated by comma. + ## Params: * array $headers = NULL @@ -41,3 +45,8 @@ Yields: array(0) { } +## Changelog: + +Version | Changes +-------------|-------- +2.5.6, 3.1.0 | Multiple headers with the same name are kept separate instead of merged together. diff --git a/http/Params.md b/http/Params.md index 7943b97..e1679b5 100644 --- a/http/Params.md +++ b/http/Params.md @@ -2,139 +2,6 @@ Parse, interpret and compose HTTP (header) parameters. -## Changelog: - -Version | Change ---------|------- -2.1.0 | Added [RFC5987](http://tools.ietf.org/html/rfc5987) support -2.5.0 | Added [RFC5988](http://tools.ietf.org/html/rfc5987) support - -## Example: - - params, $p->toString()); - - ?> - -Yields: - - array(3) { - ["p1"]=> - array(2) { - ["*rfc5987*"]=> - array(1) { - ["de"]=> - string(5) "süß" - } - ["arguments"]=> - array(0) { - } - } - ["p2"]=> - array(2) { - ["*rfc5987*"]=> - array(1) { - [""]=> - string(5) "heiß" - } - ["arguments"]=> - array(2) { - ["*rfc5987*"]=> - array(2) { - ["a1"]=> - array(1) { - [""]=> - string(3) "aß" - } - ["a2"]=> - array(1) { - [""]=> - string(3) "eß" - } - } - ["a3"]=> - string(2) "no" - } - } - ["p3"]=> - array(2) { - ["value"]=> - string(3) "not" - ["arguments"]=> - array(0) { - } - } - } - string(98) "p1*=utf-8'de's%C3%BC%C3%9F,p2*=utf-8''hei%C3%9F;a1*=utf-8''a%C3%9F;a2*=utf-8''e%C3%9F;a3=no,p3=not" - -## Web Linking Example: - - $link = <<; - rel="previous"; title*=UTF-8'de'letztes%20Kapitel, - ; - rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel - EOF; - - $p = current(http\Header::parse($link, "http\\Header"))->getParams( - http\Params::DEF_PARAM_SEP, - http\Params::DEF_ARG_SEP, - http\Params::DEF_VAL_SEP, - http\Params::PARSE_RFC5988 | http\Params::PARSE_ESCAPED - ); - - var_dump($p->params); - var_dump((string)$p); - -Yields: - - array(2) { - ["/TheBook/chapter2"]=> - array(2) { - ["value"]=> - bool(true) - ["arguments"]=> - array(2) { - ["rel"]=> - string(8) "previous" - ["*rfc5987*"]=> - array(1) { - ["title"]=> - array(1) { - ["de"]=> - string(15) "letztes Kapitel" - } - } - } - } - ["/TheBook/chapter4"]=> - array(2) { - ["value"]=> - bool(true) - ["arguments"]=> - array(2) { - ["rel"]=> - string(4) "next" - ["*rfc5987*"]=> - array(1) { - ["title"]=> - array(1) { - ["de"]=> - string(17) "nächstes Kapitel" - } - } - } - } - } - string(139) ";rel="previous";title*=utf-8'de'letztes%20Kapitel,;rel="next";title*=utf-8'de'n%C3%A4chstes%20Kapitel" - ## Constants: * DEF_PARAM_SEP diff --git a/http/Params/: Changelog.md b/http/Params/: Changelog.md new file mode 100644 index 0000000..223bb9c --- /dev/null +++ b/http/Params/: Changelog.md @@ -0,0 +1,8 @@ +# http\Params Changelog + +0. v2.1.0 + * Added constants: + * http\Params::PARSE_RFC5987 ([RFC5987](http://tools.ietf.org/html/rfc5987) support) +0. v2.5.0 + * Added constants: + * http\Params::PARSE_RFC5988 ([RFC5988](http://tools.ietf.org/html/rfc5987) support) diff --git a/http/Params/: Examples.md b/http/Params/: Examples.md new file mode 100644 index 0000000..6b56587 --- /dev/null +++ b/http/Params/: Examples.md @@ -0,0 +1,127 @@ +# http\Params Examples + +## RFC5987 example: + + params, $p->toString()); + + ?> + +### Yields: + + array(3) { + ["p1"]=> + array(2) { + ["*rfc5987*"]=> + array(1) { + ["de"]=> + string(5) "süß" + } + ["arguments"]=> + array(0) { + } + } + ["p2"]=> + array(2) { + ["*rfc5987*"]=> + array(1) { + [""]=> + string(5) "heiß" + } + ["arguments"]=> + array(2) { + ["*rfc5987*"]=> + array(2) { + ["a1"]=> + array(1) { + [""]=> + string(3) "aß" + } + ["a2"]=> + array(1) { + [""]=> + string(3) "eß" + } + } + ["a3"]=> + string(2) "no" + } + } + ["p3"]=> + array(2) { + ["value"]=> + string(3) "not" + ["arguments"]=> + array(0) { + } + } + } + string(98) "p1*=utf-8'de's%C3%BC%C3%9F,p2*=utf-8''hei%C3%9F;a1*=utf-8''a%C3%9F;a2*=utf-8''e%C3%9F;a3=no,p3=not" + +## Web Linking Example: + + $link = <<; + rel="previous"; title*=UTF-8'de'letztes%20Kapitel, + ; + rel="next"; title*=UTF-8'de'n%c3%a4chstes%20Kapitel + EOF; + + $p = current(http\Header::parse($link, "http\\Header"))->getParams( + http\Params::DEF_PARAM_SEP, + http\Params::DEF_ARG_SEP, + http\Params::DEF_VAL_SEP, + http\Params::PARSE_RFC5988 | http\Params::PARSE_ESCAPED + ); + + var_dump($p->params); + var_dump((string)$p); + +### Yields: + + array(2) { + ["/TheBook/chapter2"]=> + array(2) { + ["value"]=> + bool(true) + ["arguments"]=> + array(2) { + ["rel"]=> + string(8) "previous" + ["*rfc5987*"]=> + array(1) { + ["title"]=> + array(1) { + ["de"]=> + string(15) "letztes Kapitel" + } + } + } + } + ["/TheBook/chapter4"]=> + array(2) { + ["value"]=> + bool(true) + ["arguments"]=> + array(2) { + ["rel"]=> + string(4) "next" + ["*rfc5987*"]=> + array(1) { + ["title"]=> + array(1) { + ["de"]=> + string(17) "nächstes Kapitel" + } + } + } + } + } + string(139) ";rel="previous";title*=utf-8'de'letztes%20Kapitel,;rel="next";title*=utf-8'de'n%C3%A4chstes%20Kapitel" diff --git a/http/Url.md b/http/Url.md index 71d41e1..074099e 100644 --- a/http/Url.md +++ b/http/Url.md @@ -2,20 +2,6 @@ The http\Url class provides versatile means to parse, construct and manipulate URLs. -## Changelog: - -Version | Changes ---------|-------- -2.2.0 | Added parser constants:
http\Url::PARSE_MBUTF8,
http\Url::PARSE_MBLOC (on systems with wide character support),
http\Url::PARSE_TOPCT,
http\Url::PARSE_TOIDN (with libidn support). - -## Backwards compatibility - -### New parser in v2.2.0 - -PHP's [parse_url()](http://php.net/parse_url) is avoided since v2.2.0. - -Creating an empty url by `new http\Url(NULL, NULL, 0)` will not result in `http://localhost/` anymore but in an empty URL instead. - ## Constants: * REPLACE diff --git a/http/Url/: Changelog.md b/http/Url/: Changelog.md new file mode 100644 index 0000000..817a9e7 --- /dev/null +++ b/http/Url/: Changelog.md @@ -0,0 +1,20 @@ +# http\Url Changelog + +0. v2.2.0 + * Added parser constants: + * http\Url::PARSE_MBUTF8 + * http\Url::PARSE_MBLOC (on systems with wide character support) + * http\Url::PARSE_TOIDN (with libidn support) + * http\Url::PARSE_TOPCT + +## Backwards compatibility notes + +### New parser in v2.2.0 + +PHP's [parse_url()](http://php.net/parse_url) is avoided since v2.2.0. + +Creating an empty url by `new http\Url(NULL, NULL, 0)` will not result in `http://localhost/` anymore but in an empty URL instead. + +### No more default parts from the environment in v3.0.0 + +The default value of the $flags parameter of http\Url::__construct() was changed from http\Url::FROM_ENV to 0 and http\Env\Url was introduced instead. diff --git a/http/Url/__construct.md b/http/Url/__construct.md index d602108..cb1f771 100644 --- a/http/Url/__construct.md +++ b/http/Url/__construct.md @@ -1,14 +1,19 @@ -# void http\Url::__construct([mixed $old_url = NULL[, mixed $new_url = NULL[, int $flags = http\Url::FROM_ENV]]]) +# void http\Url::__construct([mixed $old_url = NULL[, mixed $new_url = NULL[, int $flags = 0]]]) Create an instance of an http\Url. +> ***NOTE:*** +> Prior to v3.0.0, the default for the $flags parameter was http\Url::FROM_ENV. + +See also http\Env\Url. + ## Params: * Optional mixed $old_url = NULL Initial URL parts. Either an array, object, http\Url instance or string to parse. * Optional mixed $new_url = NULL Overriding URL parts. Either an array, object, http\Url instance or string to parse. -* Optional int $flags = http\Url::FROM_ENV +* Optional int $flags = 0 The modus operandi of constructing the url. See http\Url constants. ## Throws: @@ -16,3 +21,7 @@ Create an instance of an http\Url. * http\Exception\InvalidArgumentException * http\Exception\BadUrlException +## Changelog: + +0. v3.0.0 + * Changed the default of the $flags parameter from http\Url::FROM_ENV to 0. diff --git a/http/Url/mod.md b/http/Url/mod.md index ac474ec..e283156 100644 --- a/http/Url/mod.md +++ b/http/Url/mod.md @@ -2,7 +2,8 @@ Clone this URL and apply $parts to the cloned URL. -> **Note:** This method returns a clone (copy) of this instance. +> ***NOTE:*** +> This method returns a clone (copy) of this instance. ## Params: @@ -22,6 +23,5 @@ Clone this URL and apply $parts to the cloned URL. ## Changelog: -Version | Changes ---------|-------- -2.5.0 | Added http\Url::SANITIZE_PATH to default flags. +0. v2.5.0 + * Added http\Url::SANITIZE_PATH to default flags. -- 2.30.2