README

👁 Build Status

Usage

use Seld\JsonLint\JsonParser;

$parser = new JsonParser();

// returns null if it's valid json, or a ParsingException object.
$parser->lint($json);

// Call getMessage() on the exception object to get
// a well formatted error message error like this

// Parse error on line 2:
// ... "key": "value" "numbers": [1, 2, 3]
// ----------------------^
// Expected one of: 'EOF', '}', ':', ',', ']'

// Call getDetails() on the exception to get more info.

// returns parsed json, like json_decode() does, but slower, throws
// exceptions on failure.
$parser->parse($json);

You can also pass additional flags to JsonParser::lint/parse that tweak the functionality:

• JsonParser::DETECT_KEY_CONFLICTS throws an exception on duplicate keys.
• JsonParser::ALLOW_DUPLICATE_KEYS collects duplicate keys. e.g. if you have two foo keys they will end up as foo and foo.2.
• JsonParser::PARSE_TO_ASSOC parses to associative arrays instead of stdClass objects.
• JsonParser::ALLOW_COMMENTS parses while allowing (and ignoring) inline // and multiline /* */ comments in the JSON document.
• JsonParser::ALLOW_DUPLICATE_KEYS_TO_ARRAY collects duplicate keys. e.g. if you have two foo keys the foo key will become an object (or array in assoc mode) with all foo values accessible as an array in $result->foo->__duplicates__ (or $result['foo']['__duplicates__'] in assoc mode).
• JsonParser::VALIDATE_UTF8_ENCODING validates that the whole input is well-formed UTF-8 (as defined by RFC 3629) before parsing, throwing an InvalidEncodingException that points at the first invalid byte otherwise.

Example:

$parser = new JsonParser;
try {
 $parser->parse(file_get_contents($jsonFile), JsonParser::DETECT_KEY_CONFLICTS);
} catch (DuplicateKeyException $e) {
 $details = $e->getDetails();
 echo 'Key '.$details['key'].' is a duplicate in '.$jsonFile.' at line '.$details['line'];
}

Validating UTF-8 encoding

The UTF-8 validation behind the VALIDATE_UTF8_ENCODING flag is also available as a standalone, reusable utility through the Seld\JsonLint\Utf8Validator class, should you need to validate UTF-8 encoding outside of JSON parsing:

use Seld\JsonLint\Utf8Validator;
use Seld\JsonLint\InvalidEncodingException;

try {
 // returns void on success, throws on the first invalid byte
 Utf8Validator::validate($string);
} catch (InvalidEncodingException $e) {
 // getMessage() describes the offending byte and its position
 echo $e->getMessage();
 // getDetails() returns that position information as an array
 $details = $e->getDetails();
}

Note: This library is meant to parse JSON while providing good error messages on failure. There is no way it can be as fast as php native json_decode().

It is recommended to parse with json_decode, and when it fails parse again with seld/jsonlint to get a proper error message back to the user. See for example how Composer uses this library:

Installation

For a quick install with Composer use:

composer require seld/jsonlint

JSON Lint can easily be used within another app if you have a PSR-4 autoloader, or it can be installed through Composer for use as a CLI util. Once installed via Composer you can run the following command to lint a json file or URL:

$ bin/jsonlint file.json

Requirements

• PHP 5.3+
• [optional] PHPUnit 3.5+ to execute the test suite (phpunit --version)

Submitting bugs and feature requests

Bugs and feature request are tracked on GitHub

Author

Jordi Boggiano - j.boggiano@seld.be - http://twitter.com/seldaek

License

JSON Lint is licensed under the MIT License - see the LICENSE file for details

Acknowledgements

This library is a port of the JavaScript jsonlint library.