Fonction PHP : array_merge_recursive

La fonction array_merge_recursive() en PHP combine deux tableaux ou plus en un seul. Sa caractéristique distinctive est la manière dont elle gère les clés string en doublon : au lieu de laisser une valeur ultérieure écraser une valeur antérieure, elle fusionne les deux valeurs dans un sous-tableau, en récursant dans les tableaux imbriqués au fur et à mesure. C'est le bon outil lorsque vous souhaitez conserver chaque valeur plutôt que de laisser le dernier tableau gagner.

Cette page couvre la syntaxe et les paramètres, le fonctionnement concret de la fusion récursive, la différence avec array_merge(), un cas d'usage concret, et les pièges à éviter.

Syntaxe

array_merge_recursive(array $array1, array ...$arrays): array

Paramètres

• array1 : Le premier tableau d'entrée.
• ...$arrays : Un ou plusieurs tableaux supplémentaires à fusionner.

Valeur de retour

Retourne le tableau fusionné résultant.

Comment fonctionne array_merge_recursive ?

La fonction applique deux règles différentes selon le type de clé :

• Les clés string qui apparaissent dans plusieurs tableaux sont combinées. Si les deux valeurs sont des scalaires, elles sont regroupées dans un nouveau sous-tableau ; si les deux sont des tableaux, la fonction récurse et les fusionne au niveau suivant.
• Les clés entières (numériques) ne sont jamais écrasées. Chaque élément à clé numérique est ajouté à la suite et renuméroté, de sorte que rien n'est perdu et le résultat est réindexé à partir de 0.

C'est pourquoi la fonction est dite « récursive » : chaque fois qu'elle rencontre deux tableaux sous la même clé string, elle les parcourt et répète la même logique de fusion sur leur contenu.

Remarque : Contrairement à array_merge(), qui écrase les valeurs pour les clés string en doublon et réindexe les clés numériques, array_merge_recursive() fusionne les clés string en doublon dans des tableaux imbriqués tout en préservant chaque valeur.

Voici un exemple du fonctionnement de array_merge_recursive :

Exemple PHP de la fonction array_merge_recursive

La sortie de ce code sera :

Array
(
    [color] => Array
        (
            [favorite] => Array
                (
                    [0] => red
                    [1] => green
                )
            [0] => blue
        )
    [0] => 5
    [1] => 10
)

Comme vous pouvez le constater, la fonction array_merge_recursive a fusionné les clés en doublon des tableaux d'entrée dans des sous-tableaux.

array_merge() vs. array_merge_recursive()

Voir les deux fonctions côte à côte rend la différence concrète :

<?php

$defaults  = ["roles" => ["user"],   "name" => "Guest"];
$overrides = ["roles" => ["editor"], "name" => "Ann"];

print_r(array_merge($defaults, $overrides));
print_r(array_merge_recursive($defaults, $overrides));

?>

Array                       // array_merge(): later value wins
(
    [roles] => Array
        (
            [0] => editor
        )
    [name] => Ann
)
Array                       // array_merge_recursive(): both values kept
(
    [roles] => Array
        (
            [0] => user
            [1] => editor
        )
    [name] => Array
        (
            [0] => Guest
            [1] => Ann
        )
)

Notez que même name, une simple chaîne, est devenu un array ["Guest", "Ann"]. C'est le piège principal abordé ci-dessous : la fusion récursive transforme chaque clé string répétée en liste, que vous le souhaitiez ou non.

Quand utiliser array_merge_recursive

Faites appel à cette fonction lorsque le but est de collecter des valeurs plutôt que d'en choisir une. Un cas courant est le regroupement de données — par exemple, construire une correspondance entre une catégorie et tous ses éléments :

<?php

$result = [];
$products = [
    ["category" => "fruit",     "name" => "apple"],
    ["category" => "fruit",     "name" => "pear"],
    ["category" => "vegetable", "name" => "carrot"],
];

foreach ($products as $product) {
    $result = array_merge_recursive(
        $result,
        [$product["category"] => [$product["name"]]]
    );
}

print_r($result);

?>

Array
(
    [fruit] => Array
        (
            [0] => apple
            [1] => pear
        )
    [vegetable] => Array
        (
            [0] => carrot
        )
)

Pièges

• Les clés string sont fusionnées, les clés entières sont ajoutées. Une clé string répétée produit un sous-tableau, même si les deux valeurs sont des scalaires. Si vous souhaitez que les valeurs ultérieures écrasent les précédentes, utilisez array_merge() ou array_replace_recursive().
• Les clés numériques ne sont pas préservées. Les clés entières sont toujours renumérotées à partir de 0, vous ne pouvez donc pas utiliser array_merge_recursive() pour fusionner deux tableaux par leurs clés numériques. Utilisez l'opérateur + (union) si vous avez besoin de conserver les clés telles quelles.
• La fonction ne descend que dans les tableaux. Si d'un côté se trouve un scalaire et de l'autre un array sous la même clé, les deux sont simplement rassemblés dans une liste ; le scalaire n'est pas fusionné dans le tableau.

Fonctions associées

• array_merge() — fusion plate où les clés string ultérieures écrasent les précédentes.
• array_replace_recursive() — récurse comme cette fonction mais remplace les valeurs au lieu de les collecter.
• array_combine() — construit un array à partir d'un tableau de clés et d'un tableau de valeurs séparés.

Conclusion

La fonction array_merge_recursive() est le bon choix lorsque vous souhaitez combiner des valeurs sous des clés string partagées plutôt que de les écraser — pour regrouper, agréger ou accumuler des données entre plusieurs tableaux. Gardez ses deux règles en tête (les clés string fusionnent en listes, les clés entières sont réindexées) et choisissez array_merge() ou array_replace_recursive() lorsque vous avez besoin d'un comportement « la dernière valeur gagne ».

Pratique