json_decode returns null for both invalid input and valid JSON null — distinguishing failure in PHP 8.1+

Resolution

To reliably distinguish between a decoding failure and a successful decode of a JSON null value, you must guard against null inputs to avoid PHP 8.1+ deprecation notices, call json_decode(), and immediately capture the result of json_last_error() before any other JSON-related function is executed.

Version-Safe Implementation Pattern

// 1. Guard against PHP 8.1+ deprecation notice for null arguments
if ($input === null) {
    $decoded = null;
    $isValid = false; // Or true, depending on your business logic for null input
} else {
    $decoded = json_decode($input, true);
    // 2. Atomic error check immediately following the decode
    $isValid = (json_last_error() === JSON_ERROR_NONE);
}

Technical Explanation

The ambiguity arises because json_decode() returns the PHP value null in two distinct scenarios: when the input string is the valid JSON literal "null" and when the input is malformed. Because the return value is identical, the internal error state is the only source of truth.

Confirmed Behaviors

• Error State Volatility: The value returned by json_last_error() is global to the process and is overwritten by any subsequent call to json_decode() or json_encode().
• PHP 8.1+ Deprecation: Passing a PHP null as the first argument to json_decode() now triggers a deprecation notice because internal functions are moving toward stricter type enforcement for non-nullable parameters.
• Valid Nulls: A string containing "null" is valid JSON and will result in JSON_ERROR_NONE.

Assumptions and Verification

This pattern assumes the environment is running PHP 8.1 or later. If the input variable is sourced from an external API or database, it is assumed that a PHP null (absence of value) should be handled differently than a JSON "null" (explicit null value).

Verification Steps:

1. Pass the string 'null': Verify $decoded is null and $isValid is true.
2. Pass the string 'invalid-json': Verify $decoded is null and $isValid is false.
3. Pass a PHP null: Verify no deprecation notice is emitted and the guard handles the state.