merge()

Deep-merge two JSON documents. Overlay values win on conflict.

Signature

JsonFast::merge(
    string $base,
    string $overlay,
    ?int $output = OUTPUT_ARRAY
): mixed

Parameters

Name	Type	Default	Description
$base	string	—	Base JSON document
$overlay	string	—	Document merged on top
$output	?int	OUTPUT_ARRAY	Output mode

Merge rules

• Objects — keys from $overlay replace or add to $base; nested objects merge recursively
• Arrays — typically replaced by the overlay value (not concatenated) unless your documents rely on a specific shape — test with your payload
• Scalars — overlay wins

Examples

$merged = JsonFast::merge(
    '{"name":"Allan","settings":{"theme":"dark"}}',
    '{"active":false,"settings":{"language":"en"}}'
);
/*
[
    'name' => 'Allan',
    'active' => false,
    'settings' => ['theme' => 'dark', 'language' => 'en'],
]
*/

Config defaults + user overrides:

$effective = JsonFast::merge(
    $defaultsJson,
    $userOverridesJson,
    JsonFast::OUTPUT_STRING
);

Performance

Large-document merge is handled in Rust. See benchmarks for throughput figures on multi-megabyte payloads.

Related

• diff() — see what changed between versions
• applySchema() — schema-driven defaults