README

Repair invalid JSON strings by automatically fixing common syntax errors like single quotes, unquoted keys, trailing commas, and missing brackets.

Requirements

PHP 8.3+

Installation

composer require cortexphp/json-repair

Quick Start

use Cortex\JsonRepair\JsonRepairer;

use function Cortex\JsonRepair\json_repair;
use function Cortex\JsonRepair\json_repair_decode;

// Broken JSON (single quotes, unquoted keys, trailing comma)
$broken = "{'name': 'John', age: 30, active: true,}";

$repaired = (new JsonRepairer($broken))->repair();
// {"name": "John", "age": 30, "active": true}

// Or use the helper function
$repaired = json_repair($broken);

// Repair and decode in one step
$data = (new JsonRepairer($broken))->decode();
// ['name' => 'John', 'age' => 30, 'active' => true]

// Or use the helper function
$data = json_repair_decode($broken);

Configuration Options

Omit Empty Values

When repairing JSON from streaming sources (e.g., LLM responses), you may want to remove keys with missing values instead of adding empty strings:

// Missing value - defaults to adding empty string
$broken = '{"name": "John", "age": }';
$repaired = json_repair($broken);
// {"name": "John", "age": ""}

// Remove keys with missing values
$repaired = json_repair($broken, omitEmptyValues: true);
// {"name": "John"}

Omit Incomplete Strings

Similarly, you can remove keys with incomplete string values instead of closing them:

// Incomplete string - defaults to closing the string
$broken = '{"name": "John", "bio": "A developer who';
$repaired = json_repair($broken);
// {"name": "John", "bio": "A developer who"}

// Remove keys with incomplete strings
$repaired = json_repair($broken, omitIncompleteStrings: true);
// {"name": "John"}

Using Both Options Together

Both options can be used together, which is especially useful for streaming JSON where deltas are concatenated:

$broken = '{"name": "John", "age": , "bio": "A developer who';
$repaired = json_repair($broken, omitEmptyValues: true, omitIncompleteStrings: true);
// {"name": "John"}

Using with JsonRepairer Class

You can also pass these options to the JsonRepairer constructor:

$repairer = new JsonRepairer(
    $broken,
    ensureAscii: true,
    omitEmptyValues: true,
    omitIncompleteStrings: true
);
$repaired = $repairer->repair();

Or with json_repair_decode:

$data = json_repair_decode(
    $broken,
    omitEmptyValues: true,
    omitIncompleteStrings: true
);

Logging

The library supports PSR-3 logging for debugging repair operations. Pass any PSR-3 compatible logger to see what repairs are being made:

use Psr\Log\LoggerInterface;

// Using the helper function
$repaired = json_repair($broken, logger: $logger);

// Using the class (implements LoggerAwareInterface)
$repairer = new JsonRepairer($broken);
$repairer->setLogger($logger);
$repaired = $repairer->repair();

Log messages include the position in the JSON string and a context snippet showing where the repair occurred. This is useful for:

Debugging why certain repairs are being made
Understanding how malformed JSON is being interpreted
Tracking repair operations in production environments

Credits

License

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

cortexphp / json-repair

Maintainers

Details