Entendendo a Função array_intersect_ukey() do PHP

A função array_intersect_ukey() compara as chaves de dois ou mais arrays usando um callback fornecido por você, e retorna as entradas do primeiro array cujas chaves estão presentes em todos os outros arrays. O u no nome significa comparação fornecida pelo usuário — é o irmão consciente de chaves de array_intersect_key(), com a diferença de que você decide quando duas chaves são consideradas "iguais".

Esta página explica o que a função retorna, como o callback de comparação determina o resultado e as armadilhas que vale conhecer antes de usá-la.

Quando Devo Usá-la?

Use array_intersect_ukey() quando precisar manter apenas as entradas cujas chaves se sobrepõem, mas a igualdade simples de chaves não é suficiente. Casos típicos:

• Correspondência de chaves sem distinção de maiúsculas/minúsculas — tratar Host e host como a mesma chave.
• Chaves normalizadas — ignorar espaços em branco, prefixos ou diferenças de formatação antes de comparar.
• Filtragem de um array de configuração ou requisição para as chaves que também aparecem em uma lista de permissões.

Se você precisa apenas de correspondência exata de chaves, use o built-in mais simples array_intersect_key() — sem callback necessário.

Sintaxe

array_intersect_ukey(
    array $array1,
    array $array2,
    array ...$arrays,
    callable $key_compare_func
): array

Parâmetros e Valor de Retorno

Retorna: Um array contendo cada par chave-valor de $array1 cuja chave corresponde a uma chave em todos os outros arrays. Uma chave corresponde quando o callback retorna 0.

Nota: os valores vêm apenas de $array1. Os valores armazenados sob chaves correspondentes nos outros arrays são ignorados — apenas suas chaves importam.

Exemplo Básico

<?php

function key_compare_func($key1, $key2)
{
    if ($key1 == $key2)
        return 0;
    else if ($key1 > $key2)
        return 1;
    else
        return -1;
}

$array1 = ['a' => 'green', 'b' => 'brown', 'c' => 'blue', 'red' => 3];
$array2 = ['d' => 'green', 'b' => 'yellow',  'yellow' => 10, 'red' => 'game'];
$result = array_intersect_ukey($array1, $array2, 'key_compare_func');

print_r($result);

?>

Saída:

Array
(
    [b] => brown
    [red] => 3
)

O callback compara chaves como o operador spaceship faz: retorna 0 apenas quando duas chaves são iguais. As chaves b e red existem em ambos os arrays, então suas entradas são mantidas — com os valores de $array1 (brown e 3), não de $array2.

No PHP moderno, você pode substituir todo esse auxiliar pelo operador spaceship (<=>):

<?php

$array1 = ['a' => 'green', 'b' => 'brown', 'c' => 'blue', 'red' => 3];
$array2 = ['d' => 'green', 'b' => 'yellow',  'red' => 'game'];

$result = array_intersect_ukey(
    $array1,
    $array2,
    fn($k1, $k2) => $k1 <=> $k2
);

print_r($result);

?>

Saída:

Array
(
    [b] => brown
    [red] => 3
)

Correspondência de Chaves Sem Distinção de Maiúsculas/Minúsculas

É aqui que o callback se justifica. strcasecmp() já retorna o contrato inteiro que a função espera (0 quando iguais, ignorando maiúsculas/minúsculas), então você pode passá-lo diretamente para corresponder chaves independentemente da capitalização:

<?php

$config   = ['Host' => 'localhost', 'PORT' => 8080, 'Debug' => true];
$defaults = ['host' => '0.0.0.0', 'port' => 80, 'timeout' => 30];

$shared = array_intersect_ukey($config, $defaults, 'strcasecmp');

print_r($shared);

?>

Saída:

Array
(
    [Host] => localhost
    [PORT] => 8080
)

Host corresponde a host e PORT corresponde a port mesmo com capitalização diferente, então ambos sobrevivem. Debug não tem contraparte em $defaults, então é descartado. Note que as chaves e valores mantidos estão exatamente como escritos no primeiro array.

Armadilhas

• O callback deve retornar 0 para uma correspondência. Um erro comum é escrever um callback que retorna um boolean ($k1 === $k2). true/false são convertidos para 1/0, então chaves não iguais poderiam acidentalmente "corresponder". Sempre retorne um inteiro de comparação de três vias.
• Os valores vêm apenas do primeiro array. Se dois arrays compartilham uma chave mas têm valores diferentes, o resultado mantém o valor do primeiro array.
• O callback é o último argumento, mesmo quando você passa três ou mais arrays para comparar.
• Para comparar tanto chaves quanto valores, veja array_intersect_uassoc(); para a operação oposta (chaves que não são compartilhadas), veja array_diff_ukey().

Conclusão

array_intersect_ukey() filtra um array para as entradas cujas chaves também aparecem em todos os outros arrays, usando sua própria definição de igualdade de chaves. Use-a para correspondência de chaves sem distinção de maiúsculas/minúsculas ou correspondência normalizada; recorra a array_intersect_key() quando a correspondência exata for suficiente. A regra principal a lembrar: o callback deve retornar 0 para chaves iguais, e os valores resultantes sempre vêm do primeiro array.

Prática