salsify/jsonstreamingparser

To add the streaming JSON parser to your PHP project, use Composer to require the package.

composer require salsify/json-streaming-parser

The JsonStreamingParser works by using a listener pattern similar to a SAX parser for XML. To use it, you must implement the \JsonStreamingParser\Listener interface. This interface allows your custom listener to receive events from the parser as it processes the JSON stream, enabling you to handle large documents without loading them entirely into memory.

Once your listener is implemented, pass the file stream and your listener instance to the \JsonStreamingParser\Parser class and call the parse() method.

$stream = fopen('doc.json', 'r');
$listener = new YourListener(); // YourListener must implement \JsonStreamingParser\Listener
try {
  $parser = new \JsonStreamingParser\Parser($stream, $listener);
  $parser->parse();
  fclose($stream);
} catch (Exception $e) {
  fclose($stream);
  throw $e;
}

The CorruptedJsonListener is a specialized implementation of ListenerInterface designed to construct an in-memory representation of a JSON document. It is particularly useful for repairing "cut" JSON documents—files that end unexpectedly before the structure is complete. By using this listener, you can capture the partially parsed data and then call forceEndDocument() to close all open objects and arrays, effectively reconstructing a valid JSON structure from the truncated input.

// Conceptual usage pattern
$listener = new \JsonStreamingParser\Listener\CorruptedJsonListener();
$parser = new \JsonStreamingParser\Parser($listener);

// If the stream ends prematurely, you can attempt to repair it:
$listener->forceEndDocument();
$repairedJson = $listener->getJson();

The InMemoryListener is a basic implementation of a listener that constructs a complete in-memory representation of a JSON document. While streaming parsers are typically used to avoid loading entire documents into memory, this class is useful as a reference implementation or as a starting point for building custom listeners.

After the parser has finished, you can retrieve the fully parsed JSON structure using the getJson() method.

// Example usage pattern (conceptual)
$listener = new \JsonStreamingParser\Listener\InMemoryListener();
$parser = new \JsonStreamingParser\Parser($listener);
$parser->parse($jsonString);

$json = $listener->getJson();

The RegexListener uses a mapping of regular expression strings to callables to determine which parts of the JSON stream to act upon.

setMatch(array $dataMatch)

Sets or updates the matching criteria.

Parameters:

• $dataMatch: An associative array where the key is a regular expression string representing the JSON path, and the value is a callable (e.g., an anonymous function) that receives the extracted data.

Callback Signature: function ($value, $pathSegment = [])

• $value: The data found at the matched path.
• $pathSegment: (Optional) If the regex contains a capture group, this argument contains the captured string/array.

$listener = new RegexListener();
$listener->setMatch([
    "/user/id" => function($id) { /* ... */ },
    "/items/\d+/price" => function($price) { /* ... */ }
]);

When instantiating SimpleObjectQueueListener, you can specify the data type that the callback receives using the $returnType parameter. This determines whether the parsed object is passed to your callback as an associative array or a stdClass object.

Available constants:

• SimpleObjectQueueListener::TYPE_ARRAY: Provides an associative array to the callback.
• SimpleObjectQueueListener::TYPE_OBJECT: Provides an object (stdClass) to the callback.

// To receive associative arrays:
$listener = new SimpleObjectQueueListener($callback, SimpleObjectQueueListener::TYPE_ARRAY);

// To receive objects:
$listener = new SimpleObjectQueueListener($callback, SimpleObjectQueueListener::TYPE_OBJECT);

To use the streaming parser, instantiate the JsonStreamingParser\Parser class. You must provide a PHP stream resource and an implementation of ListenerInterface which will receive events as the JSON is parsed.

Optional parameters allow you to configure the line ending, whether to emit whitespace events, and the buffer size for reading from the stream.

use JsonStreamingParser\Parser;
use Your\Custom\ListenerImplementation;

$stream = fopen('data.json', 'r');
$listener = new ListenerImplementation();

$parser = new Parser(
    $stream,           // resource
    $listener,         // ListenerInterface
    "\n",             // string (optional, default: "\n")
    false,             // bool (optional, default: false, emitWhitespace)
    8192               // int (optional, default: 8192, bufferSize)
);