array_replace_recursive — Funktion · PHP-Referenz

Signatur

array_replace_recursive(array $array, array ...$replacements): array

Beschreibung

array_replace_recursive() funktioniert ähnlich wie array_replace(), arbeitet jedoch rekursiv auf verschachtelten Arrays. Ist ein Wert in einem der Ersatz-Arrays selbst ein Array, wird die Funktion rekursiv aufgerufen, anstatt den gesamten verschachtelten Array zu überschreiben.

Die Funktion verarbeitet die übergebenen Arrays von links nach rechts: Jeder Schlüssel aus einem Ersatz-Array überschreibt den entsprechenden Schlüssel im Basis-Array. Existiert ein Schlüssel nur im Ersatz-Array, wird er dem Ergebnis-Array hinzugefügt. Existiert er nur im Basis-Array, bleibt er unverändert erhalten. Sind sowohl Basis- als auch Ersatz-Wert ein Array, erfolgt die rekursive Zusammenführung.

Besonders nützlich ist diese Funktion beim tiefen Zusammenführen von Konfigurationsarrays, bei denen verschachtelte Einstellungen selektiv überschrieben werden sollen, ohne die gesamte Struktur zu ersetzen. Im Gegensatz zu array_merge_recursive() werden bei array_replace_recursive() doppelte Schlüssel überschrieben statt zu einem Array zusammengefasst.

Werden keine Ersatz-Arrays übergeben, gibt die Funktion eine Kopie des Basis-Arrays zurück. Es können beliebig viele Ersatz-Arrays als weitere Argumente übergeben werden.

Parameter

Name	Typ	Default	Beschreibung
$array Pflicht	array		Das Basis-Array, dessen Werte ersetzt werden sollen.
$replacements	array		Ein oder mehrere Arrays, deren Werte die Einträge im Basis-Array rekursiv ersetzen oder ergänzen. Werden mehrere Arrays angegeben, werden sie von links nach rechts verarbeitet.

Rückgabewert

Typ

array

Beschreibung

Gibt das resultierende Array zurück, das die rekursiv zusammengeführten Werte aller übergebenen Arrays enthält. Das Original-Array wird nicht verändert.

Beispiele

Rekursives Ersetzen in verschachtelten Konfigurationsarrays

<?php
$default = [
    'database' => [
        'host'     => 'localhost',
        'port'     => 3306,
        'name'     => 'mydb',
    ],
    'cache' => [
        'driver'   => 'file',
        'lifetime' => 60,
    ],
    'debug' => false,
];

$custom = [
    'database' => [
        'host' => 'db.example.com',
        'name' => 'productiondb',
    ],
    'debug' => true,
];

$config = array_replace_recursive($default, $custom);
print_r($config);

Array ( [database] => Array ( [host] => db.example.com [port] => 3306 [name] => productiondb ) [cache] => Array ( [driver] => file [lifetime] => 60 ) [debug] => 1 )

Unterschied zu array_replace bei verschachtelten Arrays

<?php
$basis = [
    'farben' => ['rot', 'grün', 'blau'],
    'groesse' => 'L',
];

$ersatz = [
    'farben' => ['gelb', 'lila'],
];

// array_replace überschreibt den gesamten inneren Array
$resultat1 = array_replace($basis, $ersatz);
print_r($resultat1);

// array_replace_recursive ersetzt nur die vorhandenen Indizes
$resultat2 = array_replace_recursive($basis, $ersatz);
print_r($resultat2);

Array ( [farben] => Array ( [0] => gelb [1] => lila ) [groesse] => L ) Array ( [farben] => Array ( [0] => gelb [1] => lila [2] => blau ) [groesse] => L )

Zusammenführen mehrerer Ersatz-Arrays

<?php
$basis = [
    'einstellungen' => [
        'sprache'  => 'de',
        'zeitzone' => 'UTC',
        'thema'    => 'hell',
    ],
];

$schicht1 = [
    'einstellungen' => ['zeitzone' => 'Europe/Berlin'],
];

$schicht2 = [
    'einstellungen' => ['thema' => 'dunkel'],
];

$ergebnis = array_replace_recursive($basis, $schicht1, $schicht2);
print_r($ergebnis);

Array ( [einstellungen] => Array ( [sprache] => de [zeitzone] => Europe/Berlin [thema] => dunkel ) )

// Wichtig · Fallstricke

Achtung bei numerischen Schlüsseln: Im Gegensatz zu array_merge_recursive() werden numerisch indizierte Werte nicht angehängt, sondern anhand ihres Index ersetzt. Das bedeutet, dass Index 0 im Ersatz-Array stets Index 0 im Basis-Array überschreibt.

Kein Zusammenfassen von Werten: Wenn derselbe Schlüssel in mehreren Arrays vorkommt, wird er überschrieben — nicht zu einem Array zusammengeführt wie es array_merge_recursive() tut. Das macht array_replace_recursive() besser geeignet für Konfigurationsszenarien.

Keine Referenz-Semantik: Das Basis-Array wird nicht verändert; die Funktion gibt stets ein neues Array zurück.

Siehe auch

array_replace array_merge_recursive array_merge array_combine