From: Michael Wallner <mike@php.net>
Date: Tue, 5 Nov 2013 11:14:13 +0000 (+0100)
Subject: flush
X-Git-Url: https://git.m6w6.name/?p=mdref%2Fmdref-http;a=commitdiff_plain;h=a9966e91a49824155b1d9b3b3a580d43b20e3662

flush
---

diff --git a/http.md b/http.md
index f439b0d..bf651e2 100644
--- a/http.md
+++ b/http.md
@@ -2,7 +2,7 @@
 
 > **Note:** This documentation is work-in-progress.
 
-## About
+## About:
 
 Extended HTTP support. Again. Keep in mind that it's got the major version 2, because it's incompatible with pecl_http v1.
 
diff --git a/http/Client.md b/http/Client.md
new file mode 100644
index 0000000..e705769
--- /dev/null
+++ b/http/Client.md
@@ -0,0 +1,14 @@
+# class http\Client implements SplSubject
+
+The HTTP client.
+
+## Properties:
+
+* private $observers = NULL  
+  SplObjectStorage, attached observers.
+* protected $options = NULL  
+  Array of set options.
+* protected $history = NULL  
+  http\Message request/response history.
+* public $recordHistory = false  
+  Boolean flag whether to record instory in http\Client::$history.
diff --git a/http/Client/Curl.md b/http/Client/Curl.md
new file mode 100644
index 0000000..d0f692b
--- /dev/null
+++ b/http/Client/Curl.md
@@ -0,0 +1,245 @@
+# namespace http\Client\Curl
+
+The http\Client\Curl namespace holds option value constants specific to the curl driver of the http\Client.
+
+## Constants:
+
+### HTTP Protocol Version
+
+* HTTP_VERSION_1_0  
+  Use HTTP/1.0 protocol version.
+* HTTP_VERSION_1_1  
+  Use HTTP/1.1 protocol version.
+* HTTP_VERSION_ANY  
+  Use any HTTP protocol version.
+  
+### SSL Protocol Version
+
+* SSL_VERSION_TLSv1  
+  Use TLSv1 encryption.
+* SSL_VERSION_SSLv2  
+  Use SSLv2 encryption.
+* SSL_VERSION_SSLv3  
+  Use SSLv3 encryption.
+* SSL_VERSION_ANY  
+  Use any encryption.
+
+### DNS IP Version
+
+* IPRESOLVE_V4  
+  Use IPv4 resolver.
+* IPRESOLVE_V6  
+  Use IPv6 resolver.
+* IPRESOLVE_ANY  
+  Use any resolver.
+
+### Authentication Type
+
+* AUTH_BASIC  
+  Use Basic authentication.
+* AUTH_DIGEST  
+  Use Digest authentication.
+* AUTH_DIGEST_IE  
+  Use IE (lower v7) quirks with Digest authentication. Available if libcurl is v7.19.3 or more recent.
+* AUTH_NTLM  
+  Use NTLM authentication.
+* AUTH_GSSNEG  
+  Use GSS-Negotiate authentication.
+* AUTH_ANY  
+  Use any authentication.
+
+### Proxy Protocol Version
+
+* PROXY_SOCKS4  
+  Use SOCKSv4 proxy protocol.
+* PROXY_SOCKS4A  
+  Use SOCKSv4a proxy protocol.
+* PROXY_SOCKS5_HOSTNAME  
+  Use SOCKS5h proxy protocol.
+* PROXY_SOCKS5  
+  Use SOCKS5 proxy protoccol.
+* PROXY_HTTP  
+  Use HTTP/1.1 proxy protocol.
+* PROXY_HTTP_1_0  
+  Use HTTP/1.0 proxy protocol. Available if libcurl is v7.19.4 or more recent.
+
+### POST Redirection Behavior
+
+* POSTREDIR_301  
+  Keep POSTing on 301 redirects. Available if libcurl is v7.19.1 or more recent.
+* POSTREDIR_302  
+  Keep POSTing on 302 redirects. Available if libcurl is v7.19.1 or more recent.
+* POSTREDIR_ALL  
+  Keep POSTing on any redirect. Available if libcurl is v7.19.1 or more recent.
+
+
+## Options:
+
+### HTTP
+
+* int $protocol  
+  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.
+* int $proxyport  
+  The port number of the proxy.
+* string $proxyauth  
+  user:password
+* int $proxyauthtype  
+  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.
+
+### DNS
+
+* int $dns_cache_timeout  
+  Resolved hosts will be kept fot this number of seconds.
+* int $ipresolve  
+  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  
+  Comma separated list of custom DNS servers of the form HOST[:PORT]. Available if libcurl is v7.24.0 or more recent.
+  
+### Limits
+
+* int $low_speed_limit  
+  Minimum speed in bytes per second.
+* int $low_speed_time
+  Maximum time in seconds the transfer can be below $low_speed_limit before cancelling.
+* int $maxfilesize  
+  Maximum download size.
+
+### Connection handling
+
+* bool $fresh_connect  
+  Force a new connection.
+* bool $forbid_reuse  
+  Force closing the connection.
+
+### Networking
+
+* string $interface  
+  Outgoing interface name.
+* array $portrange  
+  A tuple of min/max ports.
+* int $port  
+  Override the URL's port.
+* int $address_scope  
+  RFC4007 zone_id. Available if libcurl is v7.19.0 or more recent.
+* bool $tcp_keepalive  
+  Whether to use TCP keepalive. Available if libcurl is v7.25.0 or more recent.
+* int $tcp_keepidle  
+  Seconds to wait before sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
+* int $tcp_keepintvl  
+  Interval in seconds to wait between sending keepalive probes. Available if libcurl is v7.25.0 or more recent.
+
+### Authentication
+
+* string $httpauth  
+  user:password
+* int $httpauthtype  
+  See http\Client\Curl::AUTH_* constants.
+
+### Redirection
+
+* int $redirect  
+  How many redirects to follow.
+* 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.
+
+### Retries
+
+* int $retrycount  
+  Retry this often.
+* float $retrydelay  
+  Pause this number of seconds between retries.
+
+### Special headers
+
+* string $referer  
+  Custom Referer header.
+* bool $autoreferer  
+  Whether to automatically send referers.
+* string $useragent  
+  Custom User-Agent header.
+* string $etag  
+  Custom ETag.
+* bool $compress  
+  Whether to request compressed content (through Accept-Encoding).
+* int $lastmodified  
+  Custom If-(Un)Modified since time. If less than zero, the current time will be added.
+
+### Resume/Ranges
+
+* int $resume  
+  Resume from this byte offset.
+* array $range  
+  Fetch specific ranges (if server supports byte ranges).
+
+### Cookies
+
+* bool $encodecookies  
+  Whether to URLencode cookies.
+* array $cookies  
+  List of custom cookies in the form ["name" => "value"].
+* bool $cookiesession  
+  Ignore previous session cookies to be loaded from $cookiestore.
+* string $cookiestore  
+  Path to a Netscape cookie file, from which cookies will be loaded resp. to which cookies will be written.
+
+### Timeouts
+
+* float $timeout  
+  Seconds the complete transfer may take.
+* float $connecttimeout  
+  Seconds the connect may take.
+
+### SSL
+
+* array $ssl  
+  Subarray of SSL related options:
+  * string $cert  
+    SSL certificate file.
+  * string $certtype  
+    Certificate type (DER, PEM). (Secure Transport additionally supports P12).
+  * string $key  
+    Private key file.
+  * string $keytype  
+    PK type (PEM, DER, ENG).
+  * string $keypasswd  
+    The password for the private key.
+  * string $engine  
+    Crypto engine to use for the private key.
+  * int $version  
+    See http\Client\Curl::SSL_VERSION_* constants.
+  * bool $verifypeer  
+    Whether to apply peer verification.
+  * bool $verifyhost  
+    Whether to apply host verification.
+  * string $cipher_list  
+    One or more cipher strings separated by colons.
+  * string $cainfo  
+    CA bundle to verify the peer with.
+  * string $capath  
+    Directory with prepared CA certs to verify the peer with.
+  * string $random_file  
+    A file used to read from to seed the random engine.
+  * string $egdsocket  
+    A Entropy Gathering Daemon socket.
+  * string $issuercert  
+    CA PEM cert for peer verification. Available if libcurl is v7.19.0 or more recent.
+  * string $crlfile  
+    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.
+
diff --git a/http/Client/Request.md b/http/Client/Request.md
new file mode 100644
index 0000000..a384550
--- /dev/null
+++ b/http/Client/Request.md
@@ -0,0 +1,15 @@
+# class http\Client\Request extends http\Message
+
+The http\Client\Request class provides an HTTP message implementation tailored to represent a request message to be sent by the client.
+
+See http\Client::enqueue().
+
+## Constants:
+
+None.
+
+## Properties:
+
+* array $options = NULL  
+  Options for this request, which override client options.
+
diff --git a/http/Client/Response.md b/http/Client/Response.md
new file mode 100644
index 0000000..0b2280a
--- /dev/null
+++ b/http/Client/Response.md
@@ -0,0 +1,11 @@
+# class http\Client\Response extends http\Message
+
+The http\Client\Response class represents an HTTP message the client returns as answer from a server to an http\Client\Request.
+
+## Constants:
+
+None.
+
+## Properties:
+
+None.
diff --git a/http/Client/Response/getCookies.md b/http/Client/Response/getCookies.md
new file mode 100644
index 0000000..15539b9
--- /dev/null
+++ b/http/Client/Response/getCookies.md
@@ -0,0 +1,39 @@
+# mixed http\Client\Response::getCookies([int $flags = 0[, array $allowed_extras = NULL]])
+
+Extract response cookies.
+Parses any "Set-Cookie" response headers into an http\Cookie list. See http\Cookie::__construct().
+
+## Params:
+
+* Optional int $flags = 0  
+  Cookie parser flags.
+* Optional array $allowed_extras = NULL  
+  List of keys treated as extras.
+
+## Returns:
+
+* array, list of http\Cookie instances.
+
+
+## Example:
+
+    <?php
+    $response = (new http\Client)
+        ->enqueue(new http\Client\Request("GET", "http://php.net/"))
+        ->send()
+        ->getResponse();
+    
+    foreach ($response->getCookies() as $cookie) {
+        /* @var $cookie http\Cookie */
+        foreach ($cookie->getCookies() as $name => $value) {
+            printf("Got a cookie named '%s' with value '%s'\n\tdomain=%s\n\t  path=%s\n", 
+                $name, $value, $cookie->getDomain(), $cookie->getPath());
+        }
+    }
+    ?>
+
+Yields:
+
+    Got a cookie named 'COUNTRY' with value 'USA,72.52.91.14'
+        domain=.php.net
+          path=/
diff --git a/http/Client/Response/getTransferInfo.md b/http/Client/Response/getTransferInfo.md
new file mode 100644
index 0000000..94eaf43
--- /dev/null
+++ b/http/Client/Response/getTransferInfo.md
@@ -0,0 +1,15 @@
+# mixed http\Response::getTransferInfo([string $name = NULL])
+
+Retrieve transfer related information after the request has completed.
+See http\Client::getTransferInfo().
+
+## Params:
+
+* Optional string $name = NULL  
+  A key to retrieve out of the transfer info.
+
+## Returns:
+
+* array, all transfer info if $name was not given.
+* mixed, the specific transfer info for $name.
+* false, if the request was not complete or $name was not found.
diff --git a/http/Client/__construct.md b/http/Client/__construct.md
new file mode 100644
index 0000000..adc6299
--- /dev/null
+++ b/http/Client/__construct.md
@@ -0,0 +1,17 @@
+# void http\Client::__construct([string $driver = NULL[, string $persistent_handle_id = NULL]])
+
+Create a new HTTP client.
+
+Currently only "curl" is supported as a $driver, and used by default.
+Persisted resources identified by $persistent_handle_id will be re-used if available. 
+
+## Params:
+
+* string $driver = NULL  
+  The HTTP client driver to employ. Currently only the default driver, "curl", is supported.
+* string $persistent_handle_id = NULL  
+  If supplied, created curl handles will be persisted with this identifier for later reuse.
+
+# Throws:
+
+* http\Exception
diff --git a/http/Client/addCookies.md b/http/Client/addCookies.md
new file mode 100644
index 0000000..69b34db
--- /dev/null
+++ b/http/Client/addCookies.md
@@ -0,0 +1,13 @@
+# http\Client http\Client::addCookies([array $cookies = NULL])
+
+Add custom cookies.
+See http\Client::setCookies().
+
+## Params:
+
+* Optional array $cookies = NULL  
+  Custom cookies to add.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/addSslOptions.md b/http/Client/addSslOptions.md
new file mode 100644
index 0000000..b31f2cf
--- /dev/null
+++ b/http/Client/addSslOptions.md
@@ -0,0 +1,13 @@
+# 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.
+
+## Params:
+
+* Optional array $ssl_options = NULL  
+  Add this SSL options.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/attach.md b/http/Client/attach.md
new file mode 100644
index 0000000..8048a3e
--- /dev/null
+++ b/http/Client/attach.md
@@ -0,0 +1,13 @@
+# http\Client http\Client::attach(SplObserver $observer)
+
+Implements SplSubject. Attach another observer.
+Attached observers will be notified with progress of each transfer.
+
+## Params:
+
+* SplObserver $observer  
+  An implementation of SplObserver.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/dequeue.md b/http/Client/dequeue.md
new file mode 100644
index 0000000..1b3fd27
--- /dev/null
+++ b/http/Client/dequeue.md
@@ -0,0 +1,18 @@
+# http\Client http\Client::dequeue(http\Client\Request $request)
+
+Dequeue the http\Client\Request $request.
+
+See http\Client::requeue(), if you want to requeue the request, instead of calling http\Client::dequeue() and then http\Client::enqueue().
+
+## Params:
+
+* http\Client\Request $request  
+  The request to cancel.
+
+## Returns:
+
+* http\Client, self.
+
+## Throws:
+
+* http\Exception.
diff --git a/http/Client/detach.md b/http/Client/detach.md
new file mode 100644
index 0000000..a4c70e6
--- /dev/null
+++ b/http/Client/detach.md
@@ -0,0 +1,12 @@
+# http\Client http\Client::detach(SplObserver $observer)
+
+Implements SplSubject. Detach $observer, which has been previously attached.
+
+## Params:
+
+* SplObserver $observer  
+  Previously attached instance of SplObserver implementation.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/enableEvents.md b/http/Client/enableEvents.md
new file mode 100644
index 0000000..de38893
--- /dev/null
+++ b/http/Client/enableEvents.md
@@ -0,0 +1,13 @@
+# http\Client http\Client::enableEvents([bool $enable = true])
+
+Enable usage of an event library like libevent, which might improve performance with big socket sets.
+
+## Params:
+
+* Optional bool $enable = true  
+  Whether to enable libevent usage.
+
+## Returns:
+
+* http\Client, self.
+
diff --git a/http/Client/enablePipelining.md b/http/Client/enablePipelining.md
new file mode 100644
index 0000000..6f19206
--- /dev/null
+++ b/http/Client/enablePipelining.md
@@ -0,0 +1,12 @@
+# http\Client http\Client::enablePipelining([bool $enable = true])
+
+Enable sending pipelined requests to the same host if the driver supports it.
+
+## Params:
+
+* Optional bool $enable = true  
+  Whether to enable pipelining.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/enqueue.md b/http/Client/enqueue.md
new file mode 100644
index 0000000..24ba8fa
--- /dev/null
+++ b/http/Client/enqueue.md
@@ -0,0 +1,33 @@
+# http\Client http\Client::enqueue(http\Client\Request $request[, callable $cb])
+
+Add another http\Client\Request to the request queue.
+If the optional callback $cb returns true, the request will be automatically dequeued.
+
+See http\Client::dequeue() and http\Client::send().
+
+## Params:
+
+* http\Client\Request $request  
+  The request to enqueue.
+* Optional callable $cb  
+  A callback to automatically call when the request has finished.
+
+## Returns:
+
+* http\Client, self.
+
+## Throws:
+
+* http\Exception.
+
+## Example:
+
+    (new http\Client)->enqueue(new http\Client\Request("GET", "http://php.net"), 
+        function(http\Client\Response $res) {
+            printf("%s returned %d\n", $res->getTransferInfo("effective_url"), $res->getResponseCode());
+            return true; // dequeue
+    })->send();
+
+Yields:
+
+    http://php.net/ returned 200
diff --git a/http/Client/getAvailableDrivers.md b/http/Client/getAvailableDrivers.md
new file mode 100644
index 0000000..02693f9
--- /dev/null
+++ b/http/Client/getAvailableDrivers.md
@@ -0,0 +1,24 @@
+# static array http\Client::getAvailableDrivers()
+
+List available drivers.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, list of supported drivers.
+
+## Example:
+
+    <?php
+    var_dump(http\Client::getAvailableDrivers());
+    ?>
+
+Yields:
+
+    array(1) {
+      [0]=>
+      string(4) "curl"
+    }
diff --git a/http/Client/getCookies.md b/http/Client/getCookies.md
new file mode 100644
index 0000000..e28864b
--- /dev/null
+++ b/http/Client/getCookies.md
@@ -0,0 +1,12 @@
+# array http\Client::getCookies()
+
+Get priorly set custom cookies.
+See http\Client::setCookies().
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, custom cookies.
diff --git a/http/Client/getHistory.md b/http/Client/getHistory.md
new file mode 100644
index 0000000..55beb65
--- /dev/null
+++ b/http/Client/getHistory.md
@@ -0,0 +1,76 @@
+# http\Message http\Client::getHistory()
+
+Simply returns the http\Message chain representing the request/response history.
+
+> **Note:** The history is only recorded while http\Client::$recordHistory is true.
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Message, the request/response message chain representing the client's history.
+
+## Example:
+
+    <?php
+    $client = new http\Client;
+    $client->enqueue(new http\Client\Request("HEAD", "http://php.net"));
+    $client->enqueue(new http\Client\Request("HEAD", "http://pecl.php.net"));
+    $client->enqueue(new http\Client\Request("HEAD", "http://pear.php.net"));
+    $client->recordHistory = true;
+    $client->send();
+    
+    echo $client->getHistory()->toString(true);
+
+Yields:
+
+    HEAD / HTTP/1.1
+    User-Agent: PECL::HTTP/2.0.0dev (PHP/5.5.5)
+    Host: pear.php.net
+    Accept: */*
+    Content-Length: 0
+
+    HTTP/1.1 200 OK
+    Date: Mon, 04 Nov 2013 15:41:48 GMT
+    Server: ...
+    X-Powered-By: PHP/5.3.6
+    Connection: close
+    Content-Type: text/html; charset=UTF-8
+    Content-Length: 0
+
+    HEAD / HTTP/1.1
+    User-Agent: PECL::HTTP/2.0.0dev (PHP/5.5.5)
+    Host: pecl.php.net
+    Accept: */*
+    Content-Length: 0
+
+    HTTP/1.1 200 OK
+    Date: Mon, 04 Nov 2013 14:34:02 GMT
+    Server: ...
+    X-Powered-By: PHP/5.2.17
+    Set-Cookie: ...
+    Expires: Thu, 19 Nov 1981 08:52:00 GMT
+    Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0
+    Pragma: no-cache
+    Connection: close
+    Content-Type: text/html; charset=ISO-8859-1
+    Content-Length: 0
+
+    HEAD / HTTP/1.1
+    User-Agent: PECL::HTTP/2.0.0dev (PHP/5.5.5)
+    Host: php.net
+    Accept: */*
+    Content-Length: 0
+
+    HTTP/1.1 200 OK
+    Server: ...
+    Date: Mon, 04 Nov 2013 14:34:08 GMT
+    Content-Type: text/html;charset=utf-8
+    Connection: keep-alive
+    X-Powered-By: PHP/5.5.4-1
+    Content-Language: en
+    Set-Cookie: ...
+    Last-Modified: Mon, 04 Nov 2013 21:00:36 GMT
+    Content-Length: 0
diff --git a/http/Client/getObservers.md b/http/Client/getObservers.md
new file mode 100644
index 0000000..fe7d0fb
--- /dev/null
+++ b/http/Client/getObservers.md
@@ -0,0 +1,15 @@
+# SplObjectStorage http\Client::getObservers()
+
+Returns the SplObjectStorage holding attached observers.
+
+## Params:
+
+None.
+
+## Returns:
+
+* SplObjectStorage, observer storage.
+
+## Throws:
+
+* http\Exception.
diff --git a/http/Client/getOptions.md b/http/Client/getOptions.md
new file mode 100644
index 0000000..d208d9d
--- /dev/null
+++ b/http/Client/getOptions.md
@@ -0,0 +1,12 @@
+# array http\Client::getOptions()
+
+Get priorly set options.
+See http\Client::setOptions().
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, options.
diff --git a/http/Client/getProgressInfo.md b/http/Client/getProgressInfo.md
new file mode 100644
index 0000000..ca7a5e9
--- /dev/null
+++ b/http/Client/getProgressInfo.md
@@ -0,0 +1,38 @@
+# object http\Client::getProgressInfo(http\Client\Request $request)
+
+Retrieve the progress information for $request.
+
+## Params:
+
+* http\Client\Request $request  
+  The request to retrieve the current progress information for.
+
+## Returns:
+
+* object, stdClass instance holding progress information.
+* NULL, if $request is not enqueued.
+
+## Throws:
+
+* http\Exception.
+
+## Example:
+
+The progress info may look like follows:
+
+    object(stdClass)#6 (7) {
+      ["started"]=>
+      bool(true)
+      ["finished"]=>
+      bool(true)
+      ["info"]=>
+      string(8) "finished"
+      ["dltotal"]=>
+      float(0)
+      ["dlnow"]=>
+      float(33561)
+      ["ultotal"]=>
+      float(0)
+      ["ulnow"]=>
+      float(0)
+    }
diff --git a/http/Client/getResponse.md b/http/Client/getResponse.md
new file mode 100644
index 0000000..e2dc7ca
--- /dev/null
+++ b/http/Client/getResponse.md
@@ -0,0 +1,36 @@
+# http\Client\Response http\Client::getResponse([http\Client\Request $request = NULL])
+
+Retrieve the corresponding reponse of an already finished request, or the last received response if $request is not set.
+
+> **Note:** If $request is NULL, then the response is removed from the internal storage (stack-like operation).
+
+## Params:
+
+* Optional http\Client\Request $request  
+  The request to fetch the stored response for.
+
+## Returns:
+
+* http\Client\Response, the stored response for the request, or the last that was received.
+* NULL, if no response was found.
+
+## Example:
+
+    <?php
+    $client = new http\Client;
+    $client->enqueue(new http\Client\Request("GET", "http://php.net"));
+    $client->enqueue(new http\Client\Request("GET", "http://pecl.php.net"));
+    $client->enqueue(new http\Client\Request("GET", "http://pear.php.net"));
+    $client->send();
+    
+    while ($res = $client->getResponse()) {
+        printf("%s returned %d\n", $res->getTransferInfo("effective_url"),
+            $res->getResponseCode());
+    }
+
+Yields:
+
+    http://php.net/ returned 200
+    http://pecl.php.net/ returned 200
+    http://pear.php.net/ returned 200
+
diff --git a/http/Client/getSslOptions.md b/http/Client/getSslOptions.md
new file mode 100644
index 0000000..cf3e233
--- /dev/null
+++ b/http/Client/getSslOptions.md
@@ -0,0 +1,12 @@
+# array http\Client::getSslOptions()
+
+Retrive priorly set SSL options.
+See http\Client::getOptions() and http\Client::setSslOptions().
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, SSL options.
diff --git a/http/Client/getTransferInfo.md b/http/Client/getTransferInfo.md
new file mode 100644
index 0000000..30d5cc9
--- /dev/null
+++ b/http/Client/getTransferInfo.md
@@ -0,0 +1,104 @@
+# object http\Client::getTransferInfo(http\Client\Request $request)
+
+Get transfer related informatioin for a running or finished request.
+
+## Params:
+
+* http\Client\Request $request  
+  The request to probe for transfer info.
+
+## Returns:
+
+* object, stdClass instance holding transfer related information.
+
+## Throws:
+
+* http\Exception.
+
+## Example:
+
+The transfer info might look as follows:
+
+    object(stdClass)#6 (36) {
+      ["effective_url"]=>
+      string(16) "https://php.net/"
+      ["response_code"]=>
+      int(302)
+      ["total_time"]=>
+      float(1.011938)
+      ["namelookup_time"]=>
+      float(0.203125)
+      ["connect_time"]=>
+      float(0.387202)
+      ["pretransfer_time"]=>
+      float(0.794423)
+      ["size_upload"]=>
+      float(0)
+      ["size_download"]=>
+      float(272)
+      ["speed_download"]=>
+      float(268)
+      ["speed_upload"]=>
+      float(0)
+      ["header_size"]=>
+      int(197)
+      ["request_size"]=>
+      int(91)
+      ["ssl_verifyresult"]=>
+      int(0)
+      ["filetime"]=>
+      int(-1)
+      ["content_length_download"]=>
+      float(272)
+      ["content_length_upload"]=>
+      float(0)
+      ["starttransfer_time"]=>
+      float(1.011835)
+      ["content_type"]=>
+      string(29) "text/html; charset=iso-8859-1"
+      ["redirect_time"]=>
+      float(0)
+      ["redirect_count"]=>
+      int(0)
+      ["connect_code"]=>
+      int(0)
+      ["httpauth_avail"]=>
+      int(0)
+      ["proxyauth_avail"]=>
+      int(0)
+      ["os_errno"]=>
+      int(0)
+      ["num_connects"]=>
+      int(1)
+      ["ssl_engines"]=>
+      array(3) {
+        [0]=>
+        string(4) "rsax"
+        [1]=>
+        string(6) "rdrand"
+        [2]=>
+        string(7) "dynamic"
+      }
+      ["cookies"]=>
+      array(0) {
+      }
+      ["redirect_url"]=>
+      string(15) "http://php.net/"
+      ["primary_ip"]=>
+      string(11) "72.52.91.14"
+      ["appconnect_time"]=>
+      float(0.794327)
+      ["condition_unmet"]=>
+      int(0)
+      ["primary_port"]=>
+      int(443)
+      ["local_ip"]=>
+      string(13) "192.168.1.120"
+      ["local_port"]=>
+      int(51507)
+      ["certinfo"]=>
+      array(0) {
+      }
+      ["error"]=>
+      string(0) ""
+    }
diff --git a/http/Client/notify.md b/http/Client/notify.md
new file mode 100644
index 0000000..d3f0b86
--- /dev/null
+++ b/http/Client/notify.md
@@ -0,0 +1,77 @@
+# http\Client http\Client::notify([http\Client\Request $request = NULL[, object $progress = NULL]])
+
+Implements SplSubject. Notify attached observers about progress with $request.
+
+## Params:
+
+* Optional http\Client\Request $request = NULL  
+  The request to notify about.
+* Optional object $progress = NULL  
+  stdClass instance holding progress information.
+
+## Returns:
+
+* http\Client, self.
+
+## Example:
+
+    <?php
+    class Observer implements SplObserver {
+        function update(SplSubject $client, http\Client\Request $request = NULL, $progress = NULL) {
+            printf("%s %d%%\n", $progress->info,
+                $progress->dltotal ? ($progress->dlnow*100/$progress->dltotal) : 0);
+        }
+    }
+    
+    $client = new http\Client;
+    
+    $client->attach(new Observer);
+    $client->enqueue(new http\Client\Request("GET", "https://php.net/images/logos/php-logo.eps"));
+    $client->send();
+    ?>
+
+May yield:
+
+    start 0%
+    setup 0%
+    setup 0%
+    setup 0%
+    setup 0%
+    setup 0%
+    resolve 0%
+    connect 0%
+    connected 0%
+    connected 0%
+    connected 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    ssl negotiation 0%
+    blacklist check 0%
+    receive 10%
+    receive 20%
+    receive 30%
+    receive 40%
+    receive 50%
+    receive 60%
+    receive 70%
+    receive 80%
+    receive 90%
+    receive 100%
+    receive 100%
+    not disconnected 100%
+    finished 100%
diff --git a/http/Client/once.md b/http/Client/once.md
new file mode 100644
index 0000000..42b7280
--- /dev/null
+++ b/http/Client/once.md
@@ -0,0 +1,41 @@
+# bool http\Client::once()
+
+Perform outstanding transfer actions.
+See http\Client::wait() for the completing interface.
+
+## Params:
+
+None.
+
+## Returns:
+
+* bool, true if there are more transfers to complete.
+
+## Example:
+
+    <?php
+    $client = new http\Client;
+    $client->enqueue(new http\Client\Request("HEAD", "http://php.net"));
+    $client->enqueue(new http\Client\Request("HEAD", "http://pecl.php.net"));
+    $client->enqueue(new http\Client\Request("HEAD", "http://pear.php.net"));
+    
+    printf("Transfers ongoing");
+    while ($client->once()) {
+        // do something else here while the network transfers are busy
+        printf(".");
+        // and then call http\Client::wait() to wait for new input
+        $client->wait();
+    }
+    printf("\n");
+    
+    while ($res = $client->getResponse()) {
+        printf("%s returned %d\n", $res->getTransferInfo("effective_url"),
+            $res->getResponseCode());
+    }
+
+Yields:
+
+    Transfers ongoing....................................................
+    http://php.net/ returned 200
+    http://pecl.php.net/ returned 200
+    http://pear.php.net/ returned 200
diff --git a/http/Client/requeue.md b/http/Client/requeue.md
new file mode 100644
index 0000000..1a3d6fe
--- /dev/null
+++ b/http/Client/requeue.md
@@ -0,0 +1,15 @@
+# http\Client http\Client::requeue(http\Client\Request $request)
+
+Requeue an http\Client\Request.
+
+The difference simply is, that this method, in contrast to http\Client::enqueue(), does not throw an http\Exception when the request to queue is already enqueued and dequeues it automatically prior enqueueing it again.
+
+
+## Params:
+
+* http\Client\Request $request  
+  The request to queue.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/reset.md b/http/Client/reset.md
new file mode 100644
index 0000000..0b292cc
--- /dev/null
+++ b/http/Client/reset.md
@@ -0,0 +1,11 @@
+# http\Client http\Client::reset()
+
+Reset the client to the initial state.
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/send.md b/http/Client/send.md
new file mode 100644
index 0000000..6ea8485
--- /dev/null
+++ b/http/Client/send.md
@@ -0,0 +1,16 @@
+# http\Client http\Client::send()
+
+Send all enqueued requests.
+See http\Client::once() and http\Client::wait() for a more fine grained interface.
+
+## Params:
+
+None.
+
+## Returns:
+
+* http\Client, self.
+
+## Throws:
+
+* http\Exception.
diff --git a/http/Client/setCookies.md b/http/Client/setCookies.md
new file mode 100644
index 0000000..415728e
--- /dev/null
+++ b/http/Client/setCookies.md
@@ -0,0 +1,13 @@
+# http\Client http\Client::setCookies([array $cookies = NULL])
+
+Set custom cookies.
+See http\Client::addCookies() and http\Client::getCookies().
+
+## Params:
+
+* Optional array $cookies = NULL  
+  Set the custom cookies to this array.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/setOptions.md b/http/Client/setOptions.md
new file mode 100644
index 0000000..370441d
--- /dev/null
+++ b/http/Client/setOptions.md
@@ -0,0 +1,16 @@
+# http\Client http\Client::setOptions([array $options = NULL])
+
+Set client options.
+See http\Client\Curl.
+
+> **Note:** Only options specified prior enqueueing a request are applied to the request.
+
+## Params:
+
+* Optional array $options = NULL  
+  The options to set.
+
+## Returns:
+
+* http\Client, self.
+
diff --git a/http/Client/setSslOptions.md b/http/Client/setSslOptions.md
new file mode 100644
index 0000000..d79f992
--- /dev/null
+++ b/http/Client/setSslOptions.md
@@ -0,0 +1,13 @@
+# http\Client http\Client::setSslOptions([array $ssl_options = NULL])
+
+Specifically set SSL options.
+See http\Client::setOptions() and http\Client\Curl::$ssl options.
+
+## Params:
+
+* Optional array $ssl_options = NULL  
+  Set SSL options to this array.
+
+## Returns:
+
+* http\Client, self.
diff --git a/http/Client/wait.md b/http/Client/wait.md
new file mode 100644
index 0000000..c7d3971
--- /dev/null
+++ b/http/Client/wait.md
@@ -0,0 +1,13 @@
+# bool http\Client::wait([float $timeout = 0])
+
+Wait for $timeout seconds for transfers to provide data.
+This is the completion call to http\Client::once().
+
+## Params:
+
+* Optional float $timeout = 0  
+  Seconds to wait for data on open sockets.
+
+## Returns:
+
+* bool, success.
diff --git a/http/Url.md b/http/Url.md
new file mode 100644
index 0000000..8069c34
--- /dev/null
+++ b/http/Url.md
@@ -0,0 +1,52 @@
+# class http\Url extends http\Object
+
+The http\Url class provides versatile means to parse, construct and manipulate URLs.
+
+## Constants:
+
+* REPLACE  
+  Replace parts of the old URL with parts of the new.
+* JOIN_PATH  
+  Whether a relative path should be joined into the old path.
+* JOIN_QUERY  
+  Whether the querystrings should be joined.
+* STRIP_USER  
+  Strip the user information from the URL.
+* STRIP_PASS  
+  Strip the password from the URL.
+* STRIP_AUTH  
+  Strip user and password information from URL (same as STRIP_USER|STRIP_PASS).
+* STRIP_PORT  
+  Do not include the port.
+* STRIP_PATH  
+  Do not include the URL path.
+* STRIP_QUERY  
+  Do not include the URL querystring.
+* STRIP_FRAMGENT  
+  Strip the fragment (hash) from the URL.
+* STRIP_ALL  
+  Strip everything except scheme and host information.
+* FROM_ENV  
+  Import initial URL parts from the SAPI environment.
+* SANITIZE_PATH  
+  Whether to sanitize the URL path (consolidate double slashes, directory jumps etc.)
+
+
+## Properties:
+
+* public $scheme = NULL  
+  The URL's scheme.
+* public $user = NULL  
+  Authenticating user.
+* public $pass = NULL  
+  Authentication password.
+* public $host = NULL  
+  Hostname/domain.
+* public $port = NULL  
+  Port.
+* public $path = NULL  
+  URL path.
+* public $query = NULL  
+  URL querystring.
+* public $fragment = NULL  
+  URL fragment (hash).
diff --git a/http/Url/__construct.md b/http/Url/__construct.md
new file mode 100644
index 0000000..6d67306
--- /dev/null
+++ b/http/Url/__construct.md
@@ -0,0 +1,17 @@
+# void http\Url::__construct([mixed $old_url = NULL[, mixed $new_url = NULL[, int $flags = http\Url::FROM_ENV]]])
+
+Create an instance of an http\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  
+  The modus operandi of constructing the url. See http\Url constants.
+
+## Throws:
+
+* http\Exception
+
diff --git a/http/Url/__toString.md b/http/Url/__toString.md
new file mode 100644
index 0000000..6ef37aa
--- /dev/null
+++ b/http/Url/__toString.md
@@ -0,0 +1,19 @@
+# string http\Url::__toString()
+
+String cast handler. Alias of http\Url::toString().
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the URL as string.
+
+## Example:
+
+    echo new http\Url;
+
+Yields:
+
+    http://localhost/
diff --git a/http/Url/mod.md b/http/Url/mod.md
new file mode 100644
index 0000000..52b1f53
--- /dev/null
+++ b/http/Url/mod.md
@@ -0,0 +1,16 @@
+# http\Url http\Url::mod(mixed $parts[, int $flags = http\Url::JOIN_PATH|http\Url::JOIN_QUERY)
+
+Clone this URL and apply $parts to the cloned URL.
+
+> **Note:** This method returns a clone (copy) of this instance.
+
+## Params:
+
+* mixed $parts  
+  New URL parts.
+* Optional int $flags = http\Url::JOIN_PATH|http\Url::JOIN_QUERY  
+  Modus operandi of URL construction. See http\Url constants.
+
+## Returns:
+
+* http\Url, clone.
diff --git a/http/Url/toArray.md b/http/Url/toArray.md
new file mode 100644
index 0000000..d800043
--- /dev/null
+++ b/http/Url/toArray.md
@@ -0,0 +1,34 @@
+# array http\Url::toArray()
+
+Retrieve the URL parts as array.
+
+## Params:
+
+None.
+
+## Returns:
+
+* array, the URL parts.
+
+## Example:
+
+    var_dump((new http\Url)->toArray());
+
+Yields:
+
+    array(7) {
+      ["scheme"]=>
+      string(4) "http"
+      ["user"]=>
+      string(0) ""
+      ["pass"]=>
+      string(0) ""
+      ["host"]=>
+      string(7) "smugmug"
+      ["path"]=>
+      string(1) "/"
+      ["query"]=>
+      string(0) ""
+      ["fragment"]=>
+      string(0) ""
+    }
diff --git a/http/Url/toString.md b/http/Url/toString.md
new file mode 100644
index 0000000..78826bd
--- /dev/null
+++ b/http/Url/toString.md
@@ -0,0 +1,11 @@
+# string http\Url::toString()
+
+Get the string prepresentation of the URL.
+
+## Params:
+
+None.
+
+## Returns:
+
+* string, the URL as string.