Comprender la función array_intersect_ukey() en PHP

La función array_intersect_ukey() compara las claves de dos o más arrays usando un callback que tú proporcionas, y devuelve las entradas del primer array cuyas claves están presentes en todos los demás arrays. La u en el nombre significa comparación suministrada por el usuario — es la variante consciente de claves de array_intersect_key(), con la diferencia de que tú decides cuándo dos claves se consideran "iguales".

Esta página explica qué devuelve la función, cómo el callback de comparación determina el resultado y los problemas que vale la pena conocer antes de usarla.

¿Cuándo usarla?

Recurre a array_intersect_ukey() cuando necesites conservar solo las entradas cuyas claves se solapan, pero la igualdad de claves simple no es suficiente. Casos típicos:

• Comparación de claves sin distinción de mayúsculas — tratar Host y host como la misma clave.
• Claves normalizadas — ignorar espacios en blanco, prefijos o diferencias de formato antes de comparar.
• Filtrar un array de configuración o de solicitud para quedarse solo con las claves que también aparecen en una lista blanca de claves permitidas.

Si solo necesitas comparación exacta de claves, usa el más sencillo array_intersect_key() — no requiere callback.

Sintaxis

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

Parámetros y valor de retorno

Devuelve: Un array que contiene cada par clave-valor de $array1 cuya clave coincide con una clave en todos los demás arrays. Una clave coincide cuando el callback devuelve 0.

Nota: los valores provienen únicamente de $array1. Los valores almacenados bajo las claves coincidentes en los demás arrays se ignoran — solo importan sus claves.

Ejemplo 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);

?>

Salida:

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

El callback compara claves como lo hace el operador spaceship: devuelve 0 solo cuando dos claves son iguales. Las claves b y red existen en ambos arrays, por lo que sus entradas se conservan — con los valores de $array1 (brown y 3), no de $array2.

En PHP moderno puedes reemplazar ese helper completo con el 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);

?>

Salida:

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

Comparación de claves sin distinción de mayúsculas

Aquí es donde el callback demuestra su utilidad. strcasecmp() ya devuelve el contrato de entero que espera la función (0 cuando son iguales, ignorando mayúsculas), por lo que puedes pasarlo directamente para comparar claves independientemente de su capitalización:

<?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);

?>

Salida:

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

Host coincide con host y PORT coincide con port aunque su capitalización difiere, por lo que ambos sobreviven. Debug no tiene contraparte en $defaults, así que se descarta. Observa que las claves y valores conservados son exactamente tal como están escritos en el primer array.

Problemas frecuentes

• El callback debe devolver 0 para una coincidencia. Un error común es escribir un callback que devuelve un boolean ($k1 === $k2). true/false se convierten en 1/0, por lo que claves no iguales "coincidirían" accidentalmente. Devuelve siempre un entero de comparación de tres vías.
• Los valores provienen solo del primer array. Si dos arrays comparten una clave pero tienen valores diferentes, el resultado conserva el valor del primer array.
• El callback es el último argumento, incluso cuando pasas tres o más arrays para comparar.
• Para comparar tanto claves como valores, consulta array_intersect_uassoc(); para la operación opuesta (claves que no se comparten), consulta array_diff_ukey().

Conclusión

array_intersect_ukey() filtra un array para quedarse con las entradas cuyas claves también aparecen en todos los demás arrays, usando tu propia definición de igualdad de claves. Úsala para comparaciones de claves sin distinción de mayúsculas o con claves normalizadas; recurre a array_intersect_key() cuando la comparación exacta es todo lo que necesitas. La regla clave a recordar: el callback debe devolver 0 para claves iguales, y los valores resultantes siempre provienen del primer array.

Práctica