This is an old revision of the document!



PHP has two functions for dealing with JSON, json_decode() and json_encode(). Unfortunately, both have suboptimal error handling. json_decode() returns null upon erroring, but null is also a possible valid result (if decoding the JSON “null”). It is only possible to know if an error occurred by calling json_last_error() or json_last_error_msg(), which return the global error state in machine-readable and human-readable forms respectively. json_encode() also uses this system, but at least does have a clear error return value. But both functions also do not halt program execution by default on error, or even throw a warning.

This situation is suboptimal, and throwing exceptions would be cleaner: there would be no confusion between error values and correct results, no (possibly outdated) global state, no program execution after the error is thrown unless explicitly handled, and error messages would be neatly traceable to their source. However, to immediately change the default behaviour of these functions would be a backwards-compatibility issue.


This RFC instead proposes adding a new option flag value for json_decode() and json_encode(), JSON_THROW_ON_ERROR. When passed this flag, the error behaviour of these functions is changed. Instead of setting the global error state, they throw a JsonException with the message and code set to whatever json_last_error() and json_last_error_msg() would otherwise be respectively.

JsonException would be a new class that subclasses Exception.

At the present time, there would be no change to the default error behaviour. It would be worthwhile considering whether to eventually deprecate not using JSON_THROW_ON_ERROR, however.

Backward Incompatible Changes

There is a small possibility of naming conflicts with existing userland code for JsonException and JSON_THROW_ON_ERROR. Since they are in the root namespace (\) and follow the pattern of existing JSON-related items, it could have been reasonably anticipated by users that such names could conflict. It would also be trivial to rename such items. Therefore, it is reasonable not to be concerned about this potential incompatibility.

Proposed PHP Version(s)

The next possible version, most likely 7.3, though as this is a small self-contained feature, it is theoretically possible it could be introduced to 7.2.x.

RFC Impact

To Existing Extensions

The JSON extension is what this RFC concerns.

To Opcache

It shouldn't have any impact on OPcache. In any case, my patch doesn't seem to have caused any problems with OPcache.

Open Issues


Unaffected PHP Functionality

JSON's default error behaviour.

Future Scope

As mentioned earlier, it may be desirable to deprecate the default behaviour eventually.

Proposed Voting Choices

This is not a language change, merely a small addition to the JSON extension, so it only technically requires a 50%+1 majority.

It would be a simple Yes/No vote on whether to accept this RFC and merge the patch.

Patches and Tests

The patch, including tests, can be found here: https://github.com/php/php-src/pull/2662


After the project is implemented, this section should contain

  1. the version(s) it was merged to
  2. a link to the git commit(s)
  3. a link to the PHP manual entry for the feature
  4. a link to the language specification section (if any)


This patch and RFC were prompted by two discussions on the php internals mailing list started by Craig Duncan concerning JSON error handling:

Rejected Features

Keep this updated with features that were discussed on the mail lists.

rfc/json_throw_on_error.1505006312.txt.gz · Last modified: 2017/09/22 13:28 (external edit)