Here is a small example:

<?php

require_once(__DIR__.'/src/__phutil_library_init__.php');

$parser = new PhutilJSONParser();
var_dump($parser->parse('{}'));
var_dump($parser->parse('{"foo": "bar"}'));
var_dump($parser->parse('{"foo": "bar",}'));

Output

array(0) {
}
array(1) {
  ["foo"]=>
  string(3) "bar"
}
PHP Fatal error:  Uncaught exception 'JsonLintParsingException' with message 'Parse error on line 1:
{"foo": "bar",}
-------------^
Expected: 'STRING' - It appears you have an extra trailing comma' in /home/joshua/workspace/github.com/phacility/libphutil/externals/jsonlint/src/Seld/JsonLint/JsonParser.php:327
Stack trace:
#0 /home/joshua/workspace/github.com/phacility/libphutil/externals/jsonlint/src/Seld/JsonLint/JsonParser.php(224): JsonLintJsonParser->parseError('Parse error on ...', Array)
#1 /home/joshua/workspace/github.com/phacility/libphutil/src/parser/PhutilJSONParser.php(17): JsonLintJsonParser->parse('{"foo": "bar",}')
#2 /home/joshua/workspace/github.com/phacility/libphutil/test.php(8): PhutilJSONParser->parse('{"foo": "bar",}')
#3 {main}
  thrown in /home/joshua/workspace/github.com/phacility/libphutil/externals/jsonlint/src/Seld/JsonLint/JsonParser.php on line 327

I'm not sure on whether we want to keep the nested directory structure in externals/jsonlint/?

Some other minor inlines.

Also, we now will have PhutilJSON and PhutilJSONParser... these should maybe be consolidated?

Consolidating the classes and throwing a more tailored exception both seem reasonable.

I think the naming change is fine, and retaining the directory structure will make diffing/updating a little bit easier if we want to pull in patches from the upstream (or try to send them anything).

OK, I'm just writing a bunch of test cases and then this should be good to go.

One inline, looks good otherwise.

Oh, I don't think they should behave similarly -- phutil_json_decode() is the desired behavior in my book. Particularly, inputs like 3, true, "0", quoted strings, etc., produce "best-effort" answers from json_decode() that are never what I expect from a reasonable API.

Upon actually reading the diff, I guess this parser also handles all that stuff?

I think the default mode should require the input to be a real JSON object ({...}) and throw if it isn't. There could be some alternate "whatever man, it's probably JSON" mode (or set of modes?) which parses bare strings, arrays, integers, etc., but I think this is rarely desired.

In D9622#37, @epriestley wrote:

I think the default mode should require the input to be a real JSON object ({...}) and throw if it isn't.

I think that JSON arrays ([...]) should be allowed too?

I think this is desirable, and we'll basically end up with a "shallow/UI" usage:

try {
  $result = parse($input);
} catch (PhutilJSONParserException $ex) {
  throw new PhutilProxyException("details about exactly what you did wrong", $ex);
}

...and a "deep/continue" usage:

try {
  $result = parse($input);
} catch (PhutilJSONParserException $ex) {
  $result = array();
}

These are a little verbose, but consistent, hard to get wrong, and seem generally reasonable to me.