Entendiendo la función PHP array_diff_key

array_diff_key() compara dos o más arrays por sus claves y devuelve las entradas del primer array cuyas claves no están presentes en ninguno de los demás arrays. La palabra clave es claves: la función nunca examina los valores. Esto la convierte en la herramienta adecuada cuando deseas eliminar o conservar elementos de un array basándote en un conjunto de claves — por ejemplo, eliminar campos no deseados de la entrada de un formulario o encontrar qué opciones de configuración faltan en una sobreescritura.

Esta página cubre la firma de la función, un ejemplo ejecutable, cómo trata los valores y las claves numéricas, los casos de uso más comunes en el mundo real y cómo difiere de las funciones relacionadas de comparación de arrays.

Sintaxis

array_diff_key(array $array, array ...$arrays): array

• $array — el array con el que comparar (el resultado solo contiene sus entradas).
• ...$arrays — uno o más arrays cuyas claves se utilizan para excluir entradas de $array.
• Devuelve un nuevo array. Cada entrada de $array se conserva solo si su clave no aparece en ninguno de los demás arrays. Las claves y los valores se preservan exactamente como estaban en $array.

Cómo funciona array_diff_key

La función recorre las claves del primer array. Para cada clave, verifica todos los demás arrays; si la clave se encuentra en alguno de ellos, esa entrada se elimina. Solo sobreviven las entradas cuyas claves son exclusivas del primer array.

Aquí hay un ejemplo práctico — comparar una lista de precios completa con los artículos que ya tienen descuento, para encontrar los artículos que todavía necesitan uno:

Ejemplo PHP del uso de array_diff_key

<?php

$prices = [
    "apple"  => 1.20,
    "banana" => 0.50,
    "cherry" => 3.00,
    "date"   => 2.10,
];

// Items that already have a discounted price.
$discounted = ["banana" => 0.40, "date" => 1.90];

// Keep only the items NOT present in $discounted (compared by key).
$result = array_diff_key($prices, $discounted);

print_r($result);

?>

La salida conserva apple y cherry porque sus claves están ausentes en $discounted. Observa que banana y date se eliminan aunque sus valores difieran entre los dos arrays — array_diff_key() ignora los valores por completo:

Array
(
    [apple] => 1.2
    [cherry] => 3
)

Comparar más de dos arrays

Puedes pasar cualquier número de arrays. Una entrada se elimina si su clave aparece en cualquiera de ellos:

<?php

$a = ["color" => "red", "size" => "M", "qty" => 5];
$b = ["color" => "blue"];
$c = ["qty" => 99];

print_r(array_diff_key($a, $b, $c));

?>

Solo queda size, porque color coincide con $b y qty coincide con $c:

Array
(
    [size] => M
)

Las claves se comparan como strings

PHP convierte todas las claves a strings antes de compararlas, por lo que la clave entera 0 y la clave string "0" se tratan como la misma clave. Esto importa cuando se mezclan claves numéricas y de string:

<?php

$nums   = [0 => "a", 1 => "b", 2 => "c"];
$remove = ["0" => "x", "2" => "y"];

print_r(array_diff_key($nums, $remove));

?>

Array
(
    [1] => b
)

Casos de uso de array_diff_key

• Lista blanca/negra de campos. Elimina las claves que no deseas de la entrada del usuario: array_diff_key($input, array_flip(['password', 'token'])) elimina esas dos claves independientemente de sus valores.
• Encontrar configuración faltante. Compara un conjunto de valores predeterminados con una configuración proporcionada por el usuario para ver qué claves quedaron fuera.
• Conciliar conjuntos de datos. Identifica registros (con clave por ID) que existen en un array pero no en otro.
• Limpiar datos de solicitud antes de pasarlos a una función que rechaza claves inesperadas.

Consejo: Si en cambio deseas conservar solo las entradas cuyas claves aparecen en otro array, usa array_intersect_key() — es la imagen espejo de array_diff_key().

array_diff_key vs. funciones relacionadas

Si necesitas una verificación adicional de valores además de la comparación de claves, usa array_diff_assoc(). Para personalizar cómo se comparan las claves (por ejemplo, coincidencia sin distinción de mayúsculas y minúsculas), usa array_diff_ukey().

Conclusión

array_diff_key() es una forma enfocada y rápida de filtrar un array según las claves de otros. Recuerda las dos reglas que suelen confundir: compara solo claves (los valores se ignoran), y las claves se convierten a strings antes de la comparación. Para comparaciones que también tengan en cuenta los valores, consulta array_diff_assoc(), y para comprobar una sola clave usa array_key_exists().

Práctica