Função PHP array_diff_ukey() - Um Guia Completo

Em PHP, a função array_diff_ukey() é uma ferramenta poderosa que pode ajudá-lo a comparar arrays e retornar a diferença entre eles com base em uma função de comparação de chaves personalizada. Neste artigo, veremos mais de perto como essa função funciona e como você pode usá-la em seus projetos PHP.

Assinatura e Parâmetros da Função

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

Esta é a notação do manual do PHP para a função. Em tempo de execução, o último argumento que você passa é sempre o callback de comparação; todos os argumentos anteriores são tratados como arrays.

Parâmetros:

• $array: O array base com o qual comparar.
• $arrays: Um ou mais arrays para comparar com o array base.
• $key_compare_func: Um callable que compara duas chaves e retorna um inteiro menor, igual ou maior que zero (o mesmo contrato que um comparador do usort).

Retorno: Um array contendo as entradas de $array cujas chaves não estão presentes em nenhum dos outros arrays. Os valores nunca são inspecionados — apenas as chaves.

Quando devo usá-la?

Na maioria das vezes, array_diff_key() é suficiente: ela remove entradas cujas chaves aparecem em outros arrays usando uma comparação de chaves simples no estilo ===. Use array_diff_ukey() apenas quando "essa chave é a mesma?" exige lógica personalizada — por exemplo, tratando chaves sem distinção de maiúsculas e minúsculas, comparando apenas o prefixo de uma chave ou normalizando strings numéricas antes de correspondê-las. Se você precisar comparar valores com um callback, veja array_udiff(); para comparar tanto chaves quanto valores, veja array_diff_uassoc().

Como Funciona a Função PHP array_diff_ukey()?

A função array_diff_ukey() recebe dois ou mais arrays como argumentos e compara suas entradas com base na função de comparação de chaves que você fornece. A função de comparação de chaves deve retornar um inteiro menor, igual ou maior que zero, dependendo do resultado da comparação.

Se o resultado da comparação for menor que zero, o primeiro argumento é considerado menor que o segundo. Se o resultado for maior que zero, o primeiro argumento é considerado maior que o segundo. Se o resultado for igual a zero, os dois argumentos são considerados iguais.

Usando a Função PHP array_diff_ukey()

Veja um exemplo de como você pode usar a função array_diff_ukey() em PHP:

Exemplo PHP de uso da função array_diff_ukey

<?php

function key_compare_func($a, $b)
{
    if ($a === $b) {
        return 0;
    }
    return ($a > $b)? 1:-1;
}

$array1 = ["a" => "green", "b" => "brown", "c" => "blue", "red"];
$array2 = ["a" => "green", "yellow", "red"];
$result = array_diff_ukey($array1, $array2, 'key_compare_func');
print_r($result);

?>

Neste exemplo, a função array_diff_ukey() é usada para comparar as entradas em $array1 e $array2 com base em uma função de comparação de chaves personalizada chamada key_compare_func. O array resultante, armazenado em $result, contém as entradas de $array1 que não estão presentes em $array2.

Observação: No callback, $a e $b representam as chaves dos arrays, não os valores.

Saída:

Array
(
    [b] => brown
    [c] => blue
)

Acompanhe o raciocínio: $array1 tem as chaves a, b, c e 0 (o "red" sem chave definida recebe a chave inteira 0). $array2 tem as chaves a, 0 e 1. As chaves a e 0 existem em ambos os arrays, portanto array_diff_ukey() remove "green" e "red" do resultado, deixando apenas as entradas cujas chaves (b, c) são únicas em $array1.

Função de Comparação de Chaves Personalizada

A função de comparação de chaves personalizada é uma parte essencial da função array_diff_ukey(), pois determina como as entradas nos dois arrays são comparadas. Veja um exemplo de uma função de comparação de chaves personalizada:

Exemplo PHP de função personalizada de comparação de chaves de array

function key_compare_func($a, $b)
{
    if ($a === $b) {
        return 0;
    }
    return ($a > $b)? 1:-1;
}

Neste exemplo, a função key_compare_func() retorna 0 se os dois argumentos forem iguais, 1 se o primeiro argumento for maior que o segundo e -1 se o primeiro argumento for menor que o segundo.

Observação sobre Type Juggling: Ao comparar chaves de tipos mistos (por exemplo, strings e inteiros), a comparação flexível do PHP no seu callback pode levar a resultados inesperados. Certifique-se de que seu callback lide explicitamente com conversão de tipos ou use comparação estrita (===) se a correspondência precisa de tipos for necessária.

Um caso prático: comparando chaves sem distinção de maiúsculas e minúsculas

O exemplo acima se comporta exatamente como o mais simples array_diff_key(). O callback personalizado só demonstra seu valor quando a comparação em si é não trivial — por exemplo, correspondendo chaves independentemente de letras maiúsculas ou minúsculas:

Mesmo que "Host" e "PORT" difiram em maiúsculas e minúsculas de "host" e "port", strcasecmp os trata como chaves iguais, portanto são removidos. Apenas Debug, que não tem correspondente em $defaults, sobrevive:

Array
(
    [Debug] => 1
)

Um simples array_diff_key() aqui teria mantido todas as três entradas, pois "Host" !== "host". Essa diferença é precisamente quando array_diff_ukey() é a ferramenta certa.

Conclusão

A função array_diff_ukey() compara arrays pelas suas chaves usando um callback que você fornece, retornando as entradas do primeiro array cujas chaves estão ausentes nos demais. Use-a quando a igualdade de chaves precisa de lógica personalizada; recorra ao mais simples array_diff_key() quando uma comparação estrita de chaves for suficiente.

Funções relacionadas que vale conhecer:

• array_diff_key() — comparação de chaves sem callback.
• array_diff_uassoc() — compara tanto as chaves (com callback) quanto os valores.
• array_udiff() — compara valores com um callback.
• array_intersect_ukey() — o inverso: mantém as entradas cujas chaves coincidem.

Prática