Fonction PHP : array_replace_recursive()

La fonction array_replace_recursive() en PHP fusionne des tableaux tout en conservant intacte la structure et les clés des tableaux d'origine. Elle remplace les éléments du premier tableau par les éléments des tableaux suivants, en descendant récursivement dans les tableaux imbriqués. C'est donc l'outil idéal lorsque vous devez superposer un tableau multidimensionnel sur un autre — par exemple, appliquer des remplacements utilisateur par-dessus une configuration par défaut sans aplatir les données imbriquées.

Ce chapitre couvre la syntaxe de la fonction, le comportement réel de la récursion, plusieurs exemples concrets (y compris avec plusieurs tableaux de remplacement), et les différences avec les fonctions apparentées comme array_replace() et array_merge_recursive().

Syntaxe

La syntaxe de la fonction array_replace_recursive() est simple : le premier argument est le tableau à modifier et les arguments suivants sont les tableaux dont les éléments seront fusionnés dans le premier tableau.

Syntaxe de la fonction PHP array_replace_recursive

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

Le premier argument est le tableau de base. Chaque tableau suivant est appliqué par-dessus lui, de gauche à droite, de sorte qu'une valeur d'un tableau ultérieur prévaut sur la même clé dans un tableau antérieur. La fonction retourne un nouveau tableau et ne modifie pas les arguments en place.

Fonctionnement

La fonction array_replace_recursive() fonctionne en itérant sur tous les éléments des tableaux passés en arguments. Pour chaque élément, la fonction vérifie si la clé existe dans le premier tableau. Si la clé n'existe pas, l'élément est simplement ajouté au premier tableau. Si la clé existe, la fonction vérifie si la valeur est un array. Si c'est le cas, la fonction s'appelle récursivement avec la valeur actuelle du premier tableau et la valeur correspondante du deuxième tableau comme arguments. Si la valeur n'est pas un array, elle est simplement remplacée par la valeur du deuxième tableau.

Ce processus est répété pour tous les tableaux suivants passés en arguments, les éléments étant ajoutés ou remplacés dans le premier tableau selon les besoins. Le résultat final est un tableau unique résultant de la fusion de tous les éléments des tableaux d'entrée. Remarque : contrairement à array_merge_recursive(), cette fonction remplace les clés numériques au lieu de les fusionner par index.

Exemples

Voici quelques exemples illustrant l'utilisation pratique de la fonction array_replace_recursive() :

Exemple PHP d'utilisation de la fonction array_replace_recursive

La sortie de ce code sera :

Array
(
    [a] => Array
        (
            [b] => d
        )
)

La récursion entre en jeu car $array1['a'] et $array2['a'] sont tous deux des tableaux, donc la fonction descend en leur sein et remplace b plutôt que d'écraser toute la branche a.

Autre exemple :

PHP : autre exemple d'utilisation de la fonction array_replace_recursive

La sortie de ce code sera :

Array
(
    [a] => d
)

Ici, la récursion ne se produit pas : $array2['a'] est la chaîne scalaire 'd', pas un array. Lorsque la valeur de remplacement n'est pas un array, la valeur existante entière (y compris tout tableau imbriqué) est écrasée intégralement. La fonction ne récurse que lorsque la valeur existe en tant qu'array des deux côtés.

Fusion de plusieurs tableaux et ajout de nouvelles clés

Vous pouvez passer autant de tableaux de remplacement que vous le souhaitez. Ils sont appliqués dans l'ordre, et les clés qui n'existent pas encore sont ajoutées plutôt que remplacées.

PHP array_replace_recursive avec plusieurs tableaux

<?php

$defaults = ['db' => ['host' => 'localhost', 'port' => 3306]];
$env      = ['db' => ['host' => 'db.internal']];
$cli      = ['db' => ['port' => 5432], 'debug' => true];

$result = array_replace_recursive($defaults, $env, $cli);

print_r($result);

?>

La sortie de ce code sera :

Array
(
    [db] => Array
        (
            [host] => db.internal
            [port] => 5432
        )

    [debug] => 1
)

Les clés imbriquées host et port sont chacune remplacées par les tableaux ultérieurs, tandis que la nouvelle clé debug est ajoutée. Cette superposition de gauche à droite est précisément la raison pour laquelle cette fonction est si pratique pour la configuration en couches.

array_replace_recursive() et les fonctions apparentées

• array_replace() effectue la même superposition mais uniquement au premier niveau — elle ne descend jamais dans les tableaux imbriqués, donc une valeur imbriquée est toujours remplacée en bloc.
• array_merge_recursive() combine les valeurs qui partagent une clé (transformant deux scalaires en un array des deux) au lieu de les remplacer, et elle renumérotent les clés entières. array_replace_recursive() conserve une seule valeur de remplacement et préserve les clés d'origine.
• array_merge() est la fusion non récursive qui renumérose également les clés entières.

Si votre objectif est « prendre ces valeurs par défaut et les remplacer par ces nouvelles valeurs », utilisez array_replace_recursive(). Si votre objectif est « collecter tout ce qui se trouve sous chaque clé », utilisez array_merge_recursive().

Conclusion

En conclusion, la fonction array_replace_recursive() en PHP offre un moyen pratique de fusionner des tableaux tout en préservant leur structure et leurs clés d'origine. Elle est particulièrement précieuse pour mettre à jour des données de configuration imbriquées ou fusionner des jeux de données structurés sans itération manuelle.

Pratique