Allow returning a Promise in onRejected then()

[ezimuel]

Q	A
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
License	MIT

What's in this PR?

This PR allows to return a Promise in the onRejected callable function for HttpRejectedPromise. Right now is only possible to return a ResponseInterface for the $onRejected($this->exception) call, see here.

Why?

I'm proposing this change because I'm trying to implement a retry mechanism for async requests (related to this issue php-http/client-common#112). I did a POC in elastic-transport-php library that is using HTTPlug. See 8.x branch for the details.

Example Usage

Using this change we can easily implements a retry mechanism as follows:

use Http\Discovery\HttpAsyncClientDiscovery;
use Http\Discovery\Psr17FactoryDiscovery;

$client = HttpAsyncClientDiscovery::find();
$requestFactory = Psr17FactoryDiscovery::findRequestFactory();
$retries = 2; // number of HTTP retries
$request = $requestFactory->createRequest("GET", "http://localhost:8080/test");

// onFulfilled callable
$onFulfilled = function (ResponseInterface $response) {
    return $response;
};
// onRejected callable
$onRejected = function (Exception $e) use ($client, $request) {
    // $request can be different, e.g. using a Round-Robin algorithm

    // try another execution
    return $client->sendAsyncRequest($request);
};
$promise = $client->sendAsyncRequest($request);
for ($i=0; $i < $retries; $i++) {
    $promise = $promise->then($onFulfilled, $onRejected);
}
// Add the last callable to manage the exceeded maximum number of retries
$promise->then($onFulfilled, function(\Exception $e) {
    throw new \Exception(sprintf(
        "Exceeded maximum number of retries (%d): %s",
        $retries,
        $e->getMessage()
    ));
});

To Do

• I'm not sure if a documentation pull request is needed

[dbu]

thank you for picking up the topic and creating this pull request. this looks good to me.

regarding documentation, i think it would make sense to add an explanation to https://docs.php-http.org/en/latest/components/promise.html

please also add a note to the CHANGELOG.md

and can you please rebase on master? i fixed the CI configuration so that all checks are green again.

[ezimuel]

@dbu I updated the CHANGELOG and I sent this PR php-http/documentation#295 for the documentation. Thanks!

[ezimuel]

@dbu I forgot to mention, I used the 2.3.0 version in the CHANGELOG and I marked the date as 2022-02-x.

[ezimuel]

@dbu anything missing on this PR? Let me know if I can help, thanks.

[dbu]

thanks a lot! here you go: https://github.com/php-http/httplug/releases/tag/2.3.0

[ezimuel]

Thanks @dbu for the quick release!