Guia Completo da Função array_uintersect() do PHP

A função array_uintersect() compara os valores de dois ou mais arrays e retorna os valores do primeiro array que também estão presentes em todos os outros. O que a diferencia de array_intersect() é o prefixo u: você fornece a lógica de comparação como um callback, controlando exatamente quando dois valores são considerados iguais.

Esta página aborda a sintaxe, como o callback de comparação funciona, exemplos executáveis e quando usar esta função em vez de suas alternativas mais simples.

Sintaxe

array_uintersect(
    array $array1,
    array $array2,
    array ...$arrays,
    callable $value_compare_func
): array

A função retorna um novo array com os valores de $array1 encontrados em todos os outros arrays, mantendo as chaves originais de $array1 intactas.

Como o callback de comparação funciona

O callback recebe dois valores e deve retornar um inteiro:

• um valor menor que 0 se o primeiro argumento for "menor que" o segundo,
• 0 se os dois valores forem considerados iguais,
• um valor maior que 0 se o primeiro for "maior que" o segundo.

Apenas um valor de retorno 0 conta como correspondência. Este é o mesmo contrato de três vias usado por funções de ordenação como usort(), razão pela qual o strcmp() embutido é um callback conveniente para strings.

array_uintersect() não realiza conversão de tipos por conta própria — toda decisão de igualdade passa pelo seu callback. Isso significa que você pode tornar a correspondência tão flexível ou restrita quanto precisar (sem distinção entre maiúsculas e minúsculas, com verificação de tipo, ciente de objetos, etc.).

Um callback simples para strings tem esta aparência:

function compare_strings($string1, $string2) {
    return strcmp($string1, $string2);
}

Exemplo básico

Aqui fazemos a interseção de três arrays de nomes de frutas usando o callback acima:

<?php

function compare_strings($string1, $string2) {
    return strcmp($string1, $string2);
}

$array1 = array("apple", "orange", "banana");
$array2 = array("orange", "banana", "kiwi");
$array3 = array("banana", "kiwi", "grape");

$result = array_uintersect($array1, $array2, $array3, "compare_strings");

print_r($result);

?>

Saída:

Array
(
    [2] => banana
)

Apenas "banana" aparece nos três arrays. Observe que a chave é 2 — esse é seu índice original em $array1, preservado no resultado. "orange" é removido porque não está presente em $array3.

Correspondência sem distinção entre maiúsculas e minúsculas

Como o callback controla toda a lógica de comparação, substituí-lo por strcasecmp() faz a interseção ignorar a capitalização das letras:

<?php

$a = ["Red", "GREEN", "Blue"];
$b = ["red", "green", "yellow"];

$result = array_uintersect($a, $b, "strcasecmp");

print_r($result);

?>

Saída:

Array
(
    [0] => Red
    [1] => GREEN
)

"Red" e "GREEN" são mantidos porque strcasecmp() os trata como iguais a "red" e "green". Os valores retornados são os do primeiro array, portanto a capitalização original é preservada.

Quando usar array_uintersect()

Use esta função quando:

• Você precisar da interseção de valores de array (não de chaves), e
• Uma simples verificação de igualdade não for suficiente — os valores são objetos, tipos mistos ou precisam de correspondência flexível/normalizada.

Se você só precisa comparar valores com a comparação padrão do PHP, array_intersect() é mais simples. Se as chaves também importam, veja array_uintersect_assoc(), e para diferença (em vez de interseção) com um callback, veja array_udiff().

Principais benefícios:

1. Encontre elementos comuns em vários arrays em uma única chamada, sem loops manuais.
2. As chaves originais do primeiro array são preservadas para facilitar o mapeamento de dados.
3. A lógica de comparação personalizada lida com tipos de dados complexos e regras de correspondência específicas.

Conclusão

array_uintersect() é a ferramenta certa quando você precisa dos valores comuns de vários arrays, mas a comparação embutida do PHP não corresponde à forma como você define igualdade. Defina um callback que retorne 0 para valores iguais, passe-o como último argumento, e a função retornará os valores correspondentes do primeiro array com suas chaves intactas.

Prática