json_decode() has the rudest failure mode in PHP: it returns null for invalid JSON, and it also returns null for the perfectly valid JSON string null. If your code treats null as "no data", every API hiccup silently becomes empty results. Proper error handling takes one flag or two function calls.
The right way: throw on error
Since PHP 7.3, the cleanest pattern is an exception:
try {
$data = json_decode($json, true, 512, JSON_THROW_ON_ERROR);
} catch (JsonException $e) {
// $e->getMessage() tells you exactly what was wrong
Log::warning('Bad JSON from API: ' . $e->getMessage());
$data = null;
}
No ambiguity: valid null decodes to null, and every parse failure raises JsonException with a precise message such as Syntax error, malformed JSON or Maximum stack depth exceeded.
The older way that still works
On legacy code, check the error state after decoding:
$data = json_decode($json, true);
if (json_last_error() !== JSON_ERROR_NONE) {
$reason = json_last_error_msg(); // e.g. "Control character error, possibly incorrectly encoded"
}
Anything written since PHP 7.3 should prefer the exception - it cannot be forgotten the way the if check can.
The five causes behind most failures
1. A UTF-8 byte order mark. Files saved as "UTF-8 with BOM" prepend three invisible bytes (EF BB BF) that JSON parsers reject. Strip it:
$json = preg_replace('/^\xEF\xBB\xBF/', '', $json);
2. Invalid UTF-8 anywhere in the payload. One Windows-1252 smart quote in an otherwise UTF-8 string fails the whole decode with Malformed UTF-8 characters. Re-encode before decoding if the source is not guaranteed UTF-8.
3. JavaScript habits. Single-quoted strings, trailing commas, unquoted keys and comments are valid in JS objects but not in JSON. If the payload comes from a hand-edited config or a pasted snippet, look for these first.
4. The response is not JSON at all. An API error page, a login redirect or an HTML maintenance page decoded as JSON gives Syntax error. Log the first hundred characters of the raw response on failure - it saves an hour of guessing.
5. Depth and size limits. The default depth of 512 is generous, but recursively generated structures can exceed it (Maximum stack depth exceeded). Very large integers also overflow silently into floats unless you pass JSON_BIGINT_AS_STRING.
In Laravel specifically
Prefer the framework's layers before decoding by hand: $request->json() and $response->json() on HTTP client responses handle the common cases, and validation with 'payload' => 'array' rules rejects bad input at the boundary. When you do decode raw strings - webhooks, queue payloads, third-party files - use JSON_THROW_ON_ERROR and let the exception carry the context.
Summary
null from json_decode() means "something failed" or "the value was null" and you cannot tell which without asking. Ask with JSON_THROW_ON_ERROR, log the raw payload on failure, and check for a BOM or encoding problem before blaming the sender. Silent nulls are how small API problems become big data problems.