[9.x] Allow HTTP client requests with retries to optionally throw RequestExceptions

[mattkingshott]

Edit: Changed to master branch at suggestion of @driesvints.

This PR addresses #40055 by adding functionality to the HTTP client so that you can prevent it from throwing a RequestException when retries are configured.

The problem

Presently, and as highlighted in the docs, the HTTP client does not throw exceptions when a request fails. As a result, you can make use of methods like failed on the response e.g.

$response = Http::get('http://example.com');

if ($response->failed())
{
    // Handle the error
}

However, if you configure retries on the HTTP client, it will throw a RequestException if all attempts fail.

$response = Http::retries(3, 1000)->get('http://example.com');

This means:

1. You cannot configure throw() on the client.
2. You cannot chain methods e.g. throw()->json().
3. You cannot use throwIf.
4. You cannot use the response's error handling methods e.g. $response->failed().

In addition, you have to wrap the request within a try/catch block if you want to handle the error.

The solution

The PR adds a fourth parameter throw to the retries method, which allows you to control whether the HTTP client should throw an exception when the retry limit is reached.

By default, this parameter is set to true to preserve backward compatibility.

Http::retries(3, 1000); // throws a RequestException if all retries fail
Http::retries(3, 1000, null, true); // throws a RequestException if all retries fail
Http::retries(3, 1000, null, false); // does not throw a RequestException if all retries fail

[koenhoeijmakers]

I think it would be clearer if we have a separate method instead of a boolean param

[mattkingshott]

I’m happy to change it if the Laravel team think it would be a better approach?

Any ideas for the method name? Maybe disableRetryExceptions()

[bryanlopezinc]

Maybe Http::catchRetriesExceptions ?

[mattkingshott]

As currently implemented, it does throw exceptions. Would that method name not imply that the default is that it doesn't?

[taylorotwell]

I don't think the boolean argument is that bad when combined with named parameters:

Http::retry(3, throw: false)->get(...);

[mattkingshott]

Woo!! 🍿🙏🏻