Json Diff Laravel Package

Getting Started

Install via Composer: composer require swaggest/json-diff. Start by comparing two JSON-encoded arrays/objects — typically decoded with json_decode() — using the JsonDiff class. The simplest use case: detect what changed between a stored config version and a new one.

use Swaggest\JsonDiff\JsonDiff;

$old = json_decode('{"name": "Alice", "age": 30}', true);
$new = json_decode('{"name": "Alice", "age": 31, "active": true}', true);

$diff = JsonDiff::diff($old, $new);
// $diff contains patch structure (e.g., ['age' => [JsonDiff::OP_SET, 31], '+active' => true])

Apply the patch later with:

$restored = JsonDiff::patch($old, $diff);
// $restored === $new

Check the JsonDiff::OP_* constants for patch operation types (SET, ADD, REMOVE, etc.).

Implementation Patterns

• Audit trails: Store diffs as compact JSON logs instead of full document snapshots (e.g., in Laravel migrations for config tables).
• Config sync: Detect differences between production and staging configs, then send only the patch to update remote services.
• API regression testing: Compare expected vs actual JSON responses programmatically, using diff output in test failures.
• Incremental updates: In real-time apps (e.g., collaborative editing), send minimal patches over WebSockets/SSE instead of full payloads.

Integrate with Laravel by creating a service provider or trait:

trait Configurable
{
    public function recordChange(array $old, array $new): void
    {
        $patch = JsonDiff::diff($old, $new);
        JsonDiffLog::create(['entity' => $this, 'patch' => $patch]);
    }
}

Use JsonDiff::diffPretty() for human-readable diffs in development/debug logs.

Gotchas and Tips

• Scalar types matter: 1 (int) vs "1" (string) produce a SET operation — ensure consistent encoding/decoding (e.g., use JSON_PRESERVE_ZERO_FRACTION or cast consistently).
• Order-sensitive arrays: By default, array elements are compared positionally. For unordered arrays (e.g., tags), configure JsonDiff::OPT_SORT_ARRAYS or preprocess arrays with sort() before diffing.
• Patches may not be idempotent: Reapplying a REMOVE op twice can fail or behave unexpectedly. Consider versioned patches or idempotent wrappers for stateful systems.
• Memory for large docs: Diffs of deeply nested or large arrays (e.g., >10k elements) can grow large — profile with Xdebug or limit depth in production.
• Custom ops: Extend JsonDiff to add custom operation types (e.g., JSON_DIFF_OP_MOVE) by extending the class and overriding buildOp().
• Debug tip: Use JsonDiff::getLastError() after operations to catch silent failures (e.g., malformed JSON input).