[9.x] Adds magic status methods and assertions

[timacdonald]

As seen with may recent PRs, there is a thirst from the community to be able to have named status code methods.

This PR aims to bring named methods to all possible places without the need for a gazillion individual methods.

Test response

$response = $this->get(/* ... */);

$response->assertConflict(); // ✅|❌

Http client response

$response = Http::get(/* ... */);

if ($response->paymentRequired()) {
    //
}

Recent attempts to add a variety of named methods:

• [9.x] Add conflict method to http client response #45718
• [9.x] Add assert methods for status code 400 and 408 #45701
• [9.x] Add paymentRequired helper to Http Client response #45698
• [9.x] Add notFound helper to Http Client response #45681
• [9.x] Add assertBadRequest to the TestResponse. #44658
• etc.

Edit: I've removed the ability to use named methods on the response factory, as we would have to handle standard responses, JSON responses, streamed responses, etc., and that feels like a lot.

[andiLeong]

@timacdonald great catch 👏 👏

[WendellAdriel]

That's amazing @timacdonald! 💪🏼

[bert-w]

I think I'd prefer $response->assertStatus(451) over $response->assertUnavailableForLegalReasons() because it uses a universal numeric code (I am not sure if the associated title/name for a status code is actually a strict spec?).

[a-bashtannik]

What about code completion?

[deleugpn]

Reading, understanding and debugging that magic is a lot harder than a few dozen of one-liner methods that are statically analysable without, err, more magic

[thinkverse]

I am not sure if the associated title/name for a status code is actually a strict spec?

It is, 451 is Unavailable for legal reasons as per RFC 7725. IANA has all status codes, their respective descriptions, and RFCs available in a public registry.

Only description that is technically wrong is 418 I'm a teapot RFC 2324, it's not in the HTTP spec, but the code itself has been marked as unused as part of RFC 9110 to reserve the April fools joke. 🙂

[taylorotwell]

Since this doesn't seem that popular of a PR 😅 maybe it is best we table this for now, or isolate all of this methods explicitly in a trait so they are self-contained and don't bloat up the main class.

[ziming]

I think the reason why there is a flood of these status code PRs is because the one for 404 got merged (link below) and people thought that would be an easy way to score a merged PR 😂. by doing it for many other status codes

#45681

Not really because there is a "thirst" from the community. I think. that said I do think 45681 should be merged as not found is such a common use case.

Same thing happen with the inspiring quotes last time.

[thinkverse]

Not really because there is a "thirst" from the community.

Possible, but I do see why that PR (45681) was made, and I can also see why it didn't get pushback from the community. Having helper functions for things that developers do often is great. Currently there are 4 helper functions for specific status codes, and those four make sense.

When calling an API you're very likely to check if the status is ok, or the API returns unauthorized because your API key is wrong, or forbidden if your permissions aren't correct, or a notFound if the endpoint is wrong.

This PR makes more sense from a DX point of view, it's easier to reason about a piece of code that reads $response->paymentRequired() than $request->status() === 402.

I think the reason why this got backlash is because for better or worse a large part of the community doesn't like "magic" methods. 🤷‍♂️

[bert-w]

Possible, but I do see why that PR (45681) was made, and I can also see why it didn't get pushback from the community. Having helper functions for things that developers do often is great.

Imho that PR #45681 should be reverted. There was not even 3 hours between the PR and the merge which probably explains why not a single comment was made. I think every single one of those status wrappers should be removed. $response->ok() is not good code since that "ok" could mean anything when we consider the rest of the Laravel framework. It is so unintuitive compared to simply stating $response->status === 200.

The only ones that might have some merrit that currently exist are successful() and failed().

(then again the whole Laravel wrapper around Guzzle is meh and just renames/adds some functions for slightly less code; I've been using the actual Guzzle package for ages and it works completely fine as is)