PHP Array Replace: Um Guia Completo

Em PHP, a função array_replace() substitui os valores de um array base pelos valores de um ou mais arrays de substituição, correspondendo por chave. Para cada chave que existe em um array posterior, esse valor sobrescreve o valor no array base; chaves que ainda não existem são acrescentadas. Os arrays originais nunca são modificados — array_replace() retorna um novo array.

Esta página aborda a sintaxe e os parâmetros de array_replace(), como ela lida com chaves string versus numéricas, como ela difere de array_merge(), e o detalhe de que ela não é recursiva (use array_replace_recursive() quando precisar mesclar arrays aninhados).

Quando usar

Utilize array_replace() quando quiser sobrescrever valores padrão: defina um array base com valores padrão e depois passe as substituições fornecidas pelo usuário como segundo argumento. Como a correspondência é feita por chave (não por posição), é a forma mais limpa de mesclar arrays de configuração onde as chaves têm significado.

Sintaxe

A sintaxe da função array_replace é a seguinte:

Sintaxe da função array_replace em PHP

array_replace ( array $array1 , array $array2 [, array $... ] ) : array

array_replace() recebe pelo menos um array e aceita qualquer número de arrays adicionais. Ela percorre os arrays de substituição da esquerda para a direita: cada valor cuja chave já existe em $array1 o sobrescreve, e cada nova chave é acrescentada. Arrays posteriores têm precedência sobre os anteriores. A função retorna o array resultante e deixa todas as entradas intactas.

Nota: chaves numéricas são correspondidas da mesma forma que chaves string — pelo valor literal da chave, não por posição. Esta é a principal diferença em relação a array_merge(), que renumera as chaves inteiras.

Parâmetros

• array1: Este é o array inicial que terá seus valores substituídos pelos valores dos outros arrays.
• array2: Este é o array cujos valores substituirão os valores em array1.
• ...: Estes são arrays adicionais opcionais, cujos valores serão usados para substituir ainda mais os valores em array1.

Exemplos

Vamos considerar alguns exemplos para entender como array_replace funciona.

Exemplo 1: Substituindo Valores em um Único Array

Exemplo PHP 1: Substituindo Valores em um Único Array usando array_replace

Saída:

Array
(
    [a] => peach
    [b] => banana
    [c] => cherry
)

Aqui a chave a existe em ambos os arrays, então $array2 a sobrescreve (apple → peach). A chave b existe apenas em $array1, portanto permanece como banana. A chave c existe apenas em $array2, portanto é acrescentada ao resultado.

Exemplo 2: Substituindo Valores em Múltiplos Arrays

Exemplo PHP 2: Substituindo Valores em Múltiplos Arrays usando array_replace

Saída:

Array
(
    [a] => peach
    [b] => blueberry
    [c] => cherry
    [d] => date
)

Os arrays de substituição são aplicados da esquerda para a direita. A chave a é definida como peach por $array2. A chave b começa como banana, mas é sobrescrita por $array3 para blueberry — o último array vence. As chaves c (de $array2) e d (de $array3) são novas, portanto são acrescentadas.

Exemplo 3: Não é recursiva — use array_replace_recursive()

array_replace() substitui valores inteiros, portanto um array aninhado em uma chave correspondente é substituído por completo em vez de mesclado. Quando você precisar de uma mesclagem profunda, use array_replace_recursive().

Exemplo PHP 3: array_replace vs array_replace_recursive

<?php

$base     = ["db" => ["host" => "localhost", "port" => 3306]];
$override = ["db" => ["host" => "example.com"]];

// array_replace overwrites the whole "db" sub-array
print_r(array_replace($base, $override));

// array_replace_recursive merges the nested arrays
print_r(array_replace_recursive($base, $override));

?>

Saída:

Array
(
    [db] => Array
        (
            [host] => example.com
        )

)
Array
(
    [db] => Array
        (
            [host] => example.com
            [port] => 3306
        )

)

Com array_replace() a port original é perdida porque todo o array db é substituído. array_replace_recursive() desce no array aninhado e mantém port.

array_replace() vs array_merge()

Ambas combinam arrays, mas tratam as chaves de forma diferente:

• Chaves string: comportam-se da mesma forma — valores posteriores sobrescrevem os anteriores.
• Chaves inteiras: array_merge() renumera sequencialmente, então os valores são acrescentados em vez de sobrescritos. array_replace() mantém as chaves inteiras e sobrescreve as correspondentes.

<?php

$a = [0 => "zero", 1 => "one"];
$b = [1 => "ONE", 2 => "two"];

print_r(array_merge($a, $b));   // integer keys renumbered
print_r(array_replace($a, $b)); // integer keys preserved

?>

Saída:

Array
(
    [0] => zero
    [1] => one
    [2] => ONE
    [3] => two
)
Array
(
    [0] => zero
    [1] => ONE
    [2] => two
)

Veja array_merge() para a comparação completa.

Conclusão

Em conclusão, a função array_replace em PHP oferece uma forma conveniente de atualizar arrays substituindo seus valores pelos valores de outros arrays. Com sua sintaxe simples e parâmetros flexíveis, ela pode ser usada em diversas situações, tornando-se uma ferramenta essencial para desenvolvedores PHP. Seja em um projeto simples ou complexo, a função array_replace pode ajudar a otimizar o processo de desenvolvimento e tornar o código mais eficiente.

Prática