Document Promise

Author: ddeboer

Diff for: components/promise.rst

@@ -1,13 +1,66 @@
 Promise
 =======
 
-Promise used for asynchronous HTTP requests.
-
-This will eventually be removed/deprecated and replaced with the upcoming Promise PSR.
+When sending asynchronous HTTP requests, a promise is returned. The promise acts
+as a proxy for the response or error result, which is not yet known.
 
 .. note::
 
-    Contract for the ``Http\Promise\Promise`` is temporary until `PSR is released`_.
-    Once it is out, we will use this PSR in the main client and deprecate the old contract.
+    Work is underway for a `Promise PSR`_. When that PSR has been released, we
+    will use it in HTTPlug and deprecate our ``Http\Promise\Promise`` interface.
+
+Asynchronous requests
+---------------------
+
+Asynchronous requests enable non-blocking HTTP operations. To execute such a
+request with HTTPlug::
+
+    $request = $messageFactory->createRequest('GET', 'http://php-http.org');
+
+    // Where $client implements HttpAsyncClient
+    $promise = $client->sendAsyncRequest($request);
+
+    // This code will be executed right after the request is sent, but before
+    // the response is returned.
+    echo 'Wow, non-blocking!';
+
+See :ref:`message-factory` on how to use message factories.
+
+Wait
+----
+
+The ``$promise`` that is returned implements ``Http\Promise\Promise``. At this
+point in time, the response is not known yet. You can be polite and wait for
+that response to arrive::
+
+    try {
+        $response = $promise->wait();
+    } catch (\Exception $exception) {
+        echo $exception->getMessage();
+    }
+
+Then
+----
+
+Instead of waiting, however, you can handle things asynchronously. Call the
+``then`` method with two arguments: one callback that will be executed if the
+request turns out to be successful and/or a second callback that will be
+executed if the request results in an error::
+
+    $promise->then(
+        // The success callback
+        function (ResponseInterface $response) {
+            echo 'Yay, we have a shiny new response!';
+
+            return $response;
+        },
+
+        // The failure callback
+        function (\Exception $exception) {
+            echo 'Oh darn, we have a problem';
+
+            throw $exception;
+        }
+    );
 
-.. _`PSR is released`: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs
+.. _`Promise PSR`: https://groups.google.com/forum/?fromgroups#!topic/php-fig/wzQWpLvNSjs