Add thowIf() and throwUnless() methods to HTTP Client

[x7ryan]

I would like to see thowIf() and throwUnless() methods added to the HTTP Client.

Sometimes you may find yourself (like me) using the HTTP Client to interact with an API that is not RESTful in its use of HTTP Status Codes. For example I am working with this one API that always returns a status code of 200, even in an error occurs and the only sign of an error is in the json response body.

throwIf() would accept 2 closures. The first (required) would be a closure to determine if the request was unsuccessful and an error should be thrown. The closure would have the response object passed in to be inspected and would simply need to return True if the request should be considered failed. Thus if the closure returns True the exception would be thrown or otherwise it would not. The second closure (optional) would contain any code that should be ran prior to throwing the error, just as the closure in throw() does.

throwUnless() would be the logical opposite of throwIf(), it would still receive the same two closures, but instead is testing if the request was successful, therefore it should throw the error unless the closure returns True confirming the request was successful.

[x7ryan]

On second thought, these would probably need a way to customize the exception thrown too, because the default exception used by throw() only includes the HTTP Status Code. And so that would be of very little use to get an exception saying you got back a 200 Status code.

[georgeboot]

throwIf() and throwUnless() are already available in the client. However, they add an ADDITIONAL check before throwing client or server exceptions.

I would also love to see a streamlined way to not only use http status codes for determining if there is an error. Many API's out there don't (properly) report status codes and it's a pain.

[x7ryan]

Ironically added just days after I posted this. #39148

maybe throwWhen() for this, though IMO throwIf should be rewritten to work regardless of the status code, with maybe a boolean defaulting to true to check status code too so as to not break backwards compatibility.

Though I find i often streamline my classes as will have only 1 or 2 methods that actually use the HTTP client anyway and all the other methods just call those so I just end up wrapping my error check in those methods.

[Angel5a]

Since #45251 you can provide any check as a closure. Doesn't it what you wanted too?

[georgeboot]

That closure is only executed if the response is 4xx or 5xx.

What we want, is to be able to provide logic what counts as an error. For example, to throw in a 200 response that actually contains a error only in the body, because the api vendor didn't follow rest.

[Angel5a]

Oh, my bad. You are right. Calling to throw() doesn't throw until 4xx or 5xx.

[Karmalakas]

Since #45251 you can provide any check as a closure. Doesn't it what you wanted too?

Sorry to revive this discussion, but maybe I'm missing something. throwIf() always throws if the status code is not a 200. It doesn't matter if my closure returns trueor false - if not 200, RequestException is thrown 😕 Am I misunderstanding the purpose of it? The docs say that if response has failed (client or server error) AND closure returns true, but that's not what I'm observing 🧐

[tobz-nz]

I agree, this is a needed/wanted feature.
While those 2 methods already exist and do slightly different jobs, a new failsIf() method to do this job would be very nice.

I think this can be done via the middleware() method, but it'd be much nicer as a dedicated feature.