[12.x] Allow setting flags for decoding json in the Http Client's Response

[cosmastech]

I really want to be able to specify that when I'm parsing JSON from a response, it should throw when receiving invalid JSON.

How to use

Call-site

$response = Http::get('https://some-api.example.com/users/123')->json(flags: JSON_BIGINT_AS_STRING);
assert($response['someBigId'] === '123343343580999843483023');

Additionally, these flags can also be passed to the object(), collect(), and fluent() methods.

$response = Http::post(
    'https://some-api.example.com/story',
    [
        'title' => 'Laravel Forever?',
        'body' => 'Not a question, a statement of fact.'
    ]
)->object(flags: JSON_THROW_ON_ERROR);

Setting a global default

You may wish to set an application level rule for how JSON is decoded. You do not have to remember to pass flags at the call site, as it will default to the application level defaults. To employ, add something like the following to your AppServiceProvider:

public function boot() {
    Request::$defaultJsonDecodingFlags = JSON_THROW_ON_ERROR;
}

// Inside your code
Http::get('https://laravel.com')->json(); // will throw a \JsonException

// Maybe we want to override the default
Http::get('https://laravel.com')->json(flags: 0); // doesn't throw a JsonException, we just get back false because laravel.com returns unparsable JSON

Bonus: Remembering how you decoded the body

Say we have a chain of functions where a Response is decoded earlier, but now I want to ensure that it is indeed parseable JSON? We memoize the flags used when decoding, and when we make another call with differing flags, we decode the JSON again.

$response = Http::get('https://laravel.com');
assert(false === $response->json());
assert(false === $response->json()); // does not decode again since we have passed no different flags

$response->json(flags: JSON_THROW_ON_ERROR); // decodes again and ❌ throws JsonException here

Breaking Change ?

I don't think so. We have set default parameters. It is possible someone overrode the class I suppose and is setting the $decoded property without also setting the flags. I'm not totally sure how that would be a problem, but something I considered.

[jaywengrow]

Laravel is the best.

[cosmastech]

All ready for another review! 🫡

Kudos on the AI demo last night.