Função PHP: array_replace_recursive()

A função array_replace_recursive() em PHP mescla arrays mantendo a estrutura e as chaves dos arrays originais intactas. Ela substitui elementos do primeiro array por elementos dos arrays subsequentes, descendo recursivamente para arrays aninhados. Isso a torna a ferramenta ideal quando você precisa sobrepor um array multidimensional a outro — por exemplo, aplicar substituições do usuário sobre uma configuração padrão sem achatar os dados aninhados.

Este capítulo aborda a sintaxe da função, como a recursão funciona na prática, vários exemplos (incluindo múltiplos arrays de substituição) e como ela difere de funções relacionadas como array_replace() e array_merge_recursive().

Sintaxe

A sintaxe da função array_replace_recursive() é direta: o primeiro argumento é o array que será modificado e os argumentos subsequentes são os arrays cujos elementos serão mesclados ao primeiro.

Sintaxe da função PHP array_replace_recursive

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

O primeiro argumento é o array base. Cada array seguinte é aplicado sobre ele, da esquerda para a direita, de modo que um valor em um array posterior tem precedência sobre a mesma chave em um anterior. A função retorna um novo array e não modifica os argumentos no local.

Como Funciona

A função array_replace_recursive() itera sobre todos os elementos dos arrays passados como argumentos. Para cada elemento, a função verifica se a chave existe no primeiro array. Se a chave não existir, o elemento é simplesmente adicionado ao primeiro array. Se a chave existir, a função verifica se o valor é um array. Se for, a função chama a si mesma recursivamente com o valor atual do primeiro array e o valor correspondente do segundo array como argumentos. Se o valor não for um array, ele é simplesmente substituído pelo valor do segundo array.

Esse processo se repete para todos os arrays subsequentes passados como argumentos, com elementos sendo adicionados ou substituídos no primeiro array conforme necessário. O resultado final é um único array resultante da mesclagem de todos os elementos dos arrays de entrada. Observação: ao contrário de array_merge_recursive(), esta função substitui chaves numéricas em vez de mesclá-las por índice.

Exemplos

A seguir, alguns exemplos de como a função array_replace_recursive() pode ser usada na prática:

Exemplo PHP de uso da função array_replace_recursive

A saída deste código será:

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

A recursão ocorre porque tanto $array1['a'] quanto $array2['a'] são arrays, portanto a função desce para eles e substitui b em vez de sobrescrever todo o ramo a.

Outro exemplo:

PHP Outro exemplo de uso da função array_replace_recursive

A saída deste código será:

Array
(
    [a] => d
)

Aqui a recursão não ocorre: $array2['a'] é a string escalar 'd', não um array. Quando o valor de substituição não é um array, todo o valor existente (incluindo qualquer array aninhado) é sobrescrito por completo. A função só recorre quando o valor existe como array em ambos os lados.

Mesclando múltiplos arrays e adicionando novas chaves

Você pode passar qualquer número de arrays de substituição. Eles são aplicados em ordem, e chaves que ainda não existem são adicionadas em vez de substituídas.

PHP array_replace_recursive com múltiplos arrays

<?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);

?>

A saída deste código será:

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

    [debug] => 1
)

As chaves aninhadas host e port são substituídas pelos arrays posteriores, enquanto a nova chave debug é anexada. Essa sobreposição da esquerda para a direita é exatamente o motivo pelo qual a função é tão útil para compor configurações em camadas.

array_replace_recursive() vs. funções relacionadas

• array_replace() realiza a mesma sobreposição, mas apenas no nível superior — nunca desce para arrays aninhados, portanto um valor aninhado é sempre substituído inteiramente.
• array_merge_recursive() combina valores que compartilham uma chave (transformando dois escalares em um array com ambos) em vez de substituí-los, e renumera chaves inteiras. array_replace_recursive() mantém um único valor substituto e preserva as chaves originais.
• array_merge() é a mesclagem não recursiva que também renumera chaves inteiras.

Se o seu objetivo é "pegar esses padrões e substituí-los por esses valores", use array_replace_recursive(). Se o seu objetivo é "reunir tudo sob cada chave", use array_merge_recursive().

Conclusão

Em conclusão, a função array_replace_recursive() em PHP oferece uma maneira conveniente de mesclar arrays preservando sua estrutura e chaves originais. Ela é particularmente valiosa para atualizar dados de configuração aninhados ou mesclar conjuntos de dados estruturados sem iteração manual.

Prática