Skip to content

Commit

Permalink
Document Promise
Browse files Browse the repository at this point in the history
  • Loading branch information
ddeboer committed Jan 3, 2016
1 parent 324d829 commit f380924
Showing 1 changed file with 59 additions and 6 deletions.
65 changes: 59 additions & 6 deletions components/promise.rst
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit f380924

Please sign in to comment.