Futures

Futures represent a computation that may have not yet completed. RingPHP uses hybrid of futures and promises to provide a consistent API that can be used for both blocking and non-blocking consumers.

Promises

You can get the result of a future when it is ready using the promise interface of a future. Futures expose a promise API via a then() method that utilizes React’s promise library. You should use this API when you do not wish to block.

use GuzzleHttp\Ring\Client\CurlMultiHandler;

$request = [
    'http_method' => 'GET',
    'uri'         => '/',
    'headers'     => ['host' => ['httpbin.org']]
];

$response = $handler($request);

// Use the then() method to use the promise API of the future.
$response->then(function ($response) {
    echo $response['status'];
});

You can get the promise used by a future, an instance of React\Promise\PromiseInterface, by calling the promise() method.

$response = $handler($request);
$promise = $response->promise();
$promise->then(function ($response) {
    echo $response['status'];
});

This promise value can be used with React’s aggregate promise functions.

Waiting

You can wait on a future to complete and retrieve the value, or dereference the future, using the wait() method. Calling the wait() method of a future will block until the result is available. The result is then returned or an exception is thrown if and exception was encountered while waiting on the the result. Subsequent calls to dereference a future will return the previously completed result or throw the previously encountered exception. Futures can be cancelled, which stops the computation if possible.

use GuzzleHttp\Ring\Client\CurlMultiHandler;

$response = $handler([
    'http_method' => 'GET',
    'uri'         => '/',
    'headers'     => ['host' => ['httpbin.org']]
]);

// You can explicitly call block to wait on a result.
$realizedResponse = $response->wait();

// Future responses can be used like a regular PHP array.
echo $response['status'];

In addition to explicitly calling the wait() function, using a future like a normal value will implicitly trigger the wait() function.

Future Responses

RingPHP uses futures to return asynchronous responses immediately. Client handlers always return future responses that implement GuzzleHttp\Ring\Future\ArrayFutureInterface. These future responses act just like normal PHP associative arrays for blocking access and provide a promise interface for non-blocking access.

use GuzzleHttp\Ring\Client\CurlMultiHandler;

$handler = new CurlMultiHandler();

$request = [
    'http_method'  => 'GET',
    'uri'          => '/',
    'headers'      => ['Host' => ['www.google.com']]
];

$response = $handler($request);

// Use the promise API for non-blocking access to the response. The actual
// response value will be delivered to the promise.
$response->then(function ($response) {
    echo $response['status'];
});

// You can wait (block) until the future is completed.
$response->wait();

// This will implicitly call wait(), and will block too!
$response['status'];

Important

Futures that are not completed by the time the underlying handler is destructed will be completed when the handler is shutting down.

Cancelling

Futures can be cancelled if they have not already been dereferenced.

RingPHP futures are typically implemented with the GuzzleHttp\Ring\Future\BaseFutureTrait. This trait provides the cancellation functionality that should be common to most implementations. Cancelling a future response will try to prevent the request from sending over the wire.

When a future is cancelled, the cancellation function is invoked and performs the actual work needed to cancel the request from sending if possible (e.g., telling an event loop to stop sending a request or to close a socket). If no cancellation function is provided, then a request cannot be cancelled. If a cancel function is provided, then it should accept the future as an argument and return true if the future was successfully cancelled or false if it could not be cancelled.

Wrapping an existing Promise

You can easily create a future from any existing promise using the GuzzleHttp\Ring\Future\FutureValue class. This class’s constructor accepts a promise as the first argument, a wait function as the second argument, and a cancellation function as the third argument. The dereference function is used to force the promise to resolve (for example, manually ticking an event loop). The cancel function is optional and is used to tell the thing that created the promise that it can stop computing the result (for example, telling an event loop to stop transferring a request).

use GuzzleHttp\Ring\Future\FutureValue;
use React\Promise\Deferred;

$deferred = new Deferred();
$promise = $deferred->promise();

$f = new FutureValue(
    $promise,
    function () use ($deferred) {
        // This function is responsible for blocking and resolving the
        // promise. Here we pass in a reference to the deferred so that
        // it can be resolved or rejected.
        $deferred->resolve('foo');
    }
);