HTTP client response json method without key argument doesn't respect default argument

[michaeldzjap]

Laravel Version

13.8.0

PHP Version

8.5.5

Database Driver & Version

No response

Description

A call to Illuminate\Http\Client\Response#json(default: []) does not respect the passed in default value. In other words: if the result of the aforementioned call is null this will be the value that will be returned instead of []. This is not logical in my opinion.

Whether this is a bug or not is perhaps debatable. From my (API consumer) perspective it is at least, as it doesn't make sense that passing in a key argument does respect the passed in default. I would at least expect it to be noted in the HTTP client documentation somewhere.

A fix seems easy enough: just replace return $this->decoded; with return $this->decoded ?? $default; here. Although you could argue that this will perhaps introduce a breaking change.

Steps To Reproduce

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

// Assuming there is no response payload this returns `null` instead of `[]`, which doesn't seem logical
$response->json(default: []);

[mostafa8722]

Thanks for raising this.

The current behavior of Illuminate\Http\Client\Response::json() is intentional rather than a bug.

When calling:

$response->json();

Laravel returns the fully decoded JSON payload ($this->decoded) and the $default parameter is only applied when a specific key is requested internally via data_get().

So in the case of the root payload, the $default value is not used, which is why null is returned if the decoded response is null.

Changing this to:

return $this->decoded ?? $default;

would indeed make the behavior more intuitive in some cases, but it would also introduce a breaking change for existing applications that rely on null being returned for empty or invalid JSON responses.

As a workaround, consumers can explicitly handle it:

$response->json() ?? [];

or wrap it in a helper/macro if needed for consistency across the project.

If there is interest in changing this behavior, it may require a deprecation path or a dedicated proposal to evaluate backward compatibility impact.

[michaeldzjap]

Yeah, I get the breaking change thing for sure.

It did catch me out though. Like I said before, from an API interface perspective it doesn't make much sense that the default parameter only actually gets respected in the case when you also supply a key argument. Seems inconsistent behaviour. But I guess its the way it is. Changing it now probably is not desirable. But then I do think it would make sense to at least mention it somewhere in the documentation.