JSON5 for PHP - JSON for Humans

This library is a PHP fork of the JSON5 reference implementation.

JSON5 is a JS-compatible extension to JSON which allows comments, trailing commas, single-quoted strings, and more:

{
    foo: 'bar',
    while: true,

    this: 'is a \
multi-line string',

    // this is an inline comment
    here: 'is another', // inline comment

    /* this is a block comment
       that continues on another line */

    hex: 0xDEADbeef,
    half: .5,
    delta: +10,
    to: Infinity,   // and beyond!

    finally: 'a trailing comma',
    oh: [
        "we shouldn't forget",
        'arrays can have',
        'trailing commas too',
    ],
}

See the JSON5 website for additional examples and details.

Install

Via Composer

$ composer require colinodell/json5

Usage

This package adds a json5_decode() function which is a drop-in replacement for PHP's built-in json_decode():

$json = file_get_contents('foo.json5');
$data = json5_decode($json);

It takes the same exact parameters in the same order. For more details on these, see the PHP docs.

To achieve the best possible performance, it'll try parsing with PHP's native function (which usually fails fast) and then falls back to JSON5.

Exceptions

This function will always throw a SyntaxError exception if parsing fails. This is a subclass of the new \JsonException introduced in PHP 7.3. Providing or omitting the JSON_THROW_ON_ERROR option will have no effect on this behavior.

For users on PHP 7.2 and below: a PHP 7.3 polyfill is included with this library so that you can safely reference \JsonException and JSON_THROW_ON_ERROR in your own code.

Binary / Executable

A binary/executable named json5 is also provided for converting JSON5 to plain JSON via your terminal.

Usage: json5 [OPTIONS] [FILE]

  -h, --help  Shows help and usage information

  (Reading data from STDIN is not currently supported on Windows)

Examples:

Converting a file named file.json5:

json5 file.json5

Converting a file and saving its output:

json5 file.json5 > file.json

Converting from STDIN:

echo -e "{hello: 'world!'}" | json5

Converting from STDIN and saving the output:

echo -e "{hello: 'world!'}" | json5 > output.json

Change log

Please see CHANGELOG for more information on what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING and CODE_OF_CONDUCT for details.

Security

If you discover any security related issues, please email [email protected] instead of using the issue tracker.

Support

In addition to standard support, consider a Tidelift Subscription for professional support and get alerted when new releases or security issues come out.

Credits

• Colin O'Dell
• Aseem Kishore, the JSON5 project, and their contributors
• All other contributors to this project

License

The MIT License (MIT). Please see License File for more information.