Entendendo a Função array_diff_uassoc do PHP

array_diff_uassoc() compara dois (ou mais) arrays com uma verificação de chave adicional, permitindo que você forneça sua própria função para comparar as chaves. Ela retorna cada entrada do primeiro array cujo par chave/valor não corresponde em nenhum dos outros arrays. Esta página explica a assinatura, detalha exatamente como a correspondência funciona e mostra quando usá-la em vez das funções de diferença de array mais simples.

O "u" no nome significa comparação de chave fornecida pelo usuário; o "assoc" significa que as chaves também são verificadas (uma comparação associativa).

Assinatura

array_diff_uassoc(
    array $array,
    array ...$arrays,
    callable $key_compare_func
): array

• $array — o array a ser comparado a partir de. Suas entradas aparecem no resultado.
• $arrays — um ou mais arrays para comparar contra.
• $key_compare_func — um callback fn(mixed $a, mixed $b): int que retorna 0 quando duas chaves são consideradas iguais, e um inteiro negativo/positivo caso contrário (o mesmo contrato <=> usado pelo usort). Funções nativas como strcasecmp se encaixam nesse formato.

Ela retorna um novo array; os arrays originais não são modificados.

Como funciona a comparação

Esta é a parte que confunde as pessoas. array_diff_uassoc() mantém uma entrada de $array somente se ambas as condições a seguir forem verdadeiras para ela em relação aos outros arrays:

1. O valor não corresponde (os valores são comparados com a regra usual, loose == após conversão para string — a mesma regra que array_diff() usa), ou
2. A chave não corresponde de acordo com o seu $key_compare_func.

Dito de outra forma: uma entrada é removida somente quando outro array contém o mesmo valor sob uma chave que o seu callback trata como igual. Portanto, o callback personalizado governa as chaves; os valores ainda são comparados pela regra nativa do PHP. Esse último ponto é o equívoco mais comum — o callback é apenas para as chaves.

Exemplo

Comparar listas de preços com chaves sem distinção de maiúsculas/minúsculas

Saída:

Array
(
    [Banana] => 0.5
    [Cherry] => 3
)

Percorrendo cada entrada de $prices:

• Apple => 1.20 — strcasecmp("Apple", "apple") é 0, portanto as chaves correspondem, e o valor 1.20 também corresponde a $updated["apple"]. Ambos correspondem, então é removido.
• Banana => 0.50 — as chaves correspondem (strcasecmp("Banana", "banana") === 0), mas os valores diferem (0.50 vs 0.75). Como o valor não corresponde, a entrada é mantida.
• Cherry => 3.00 — nenhuma chave em $updated corresponde, então é mantida.

Isso demonstra a regra em ação: uma chave correspondente por si só não é suficiente para remover uma entrada — o valor também precisa corresponder.

Funções de diferença relacionadas

array_diff_uassoc() faz parte de uma família de funções de diferença de array. Escolha aquela cuja estratégia de comparação corresponde aos seus dados:

• array_diff() — compara apenas os valores; as chaves são ignoradas.
• array_diff_assoc() — compara chaves e valores com as regras nativas (sem callbacks).
• array_diff_key() — compara apenas as chaves, com comparação nativa.
• array_diff_ukey() — compara apenas as chaves, mas com um callback para as chaves.
• array_udiff() — compara os valores com um callback; chaves ignoradas.
• array_udiff_assoc() — callback para valores, verificação nativa nas chaves.
• array_udiff_uassoc() — callbacks para ambos os valores e as chaves.

Quando usá-la?

Use array_diff_uassoc() quando as chaves são importantes para a comparação, mas a correspondência de chaves padrão é muito rígida — por exemplo, quando as chaves diferem apenas em maiúsculas/minúsculas ou formatação, ou quando as chaves são objetos/valores que precisam de lógica personalizada para serem considerados "iguais". Se você só se preocupa com os valores, use array_udiff(); se precisar de um callback também para os valores, use array_udiff_uassoc().

Conclusão

array_diff_uassoc() retorna as entradas do primeiro array que não têm correspondência de chave/valor nos outros arrays, usando um callback que você fornece para decidir quando duas chaves são iguais. Lembre-se de que os valores ainda são comparados pela regra nativa do PHP — uma entrada é preservada a menos que tanto a sua chave quanto o seu valor sejam encontrados em outro array.

Prática