Entendendo a Função PHP array_diff_key

array_diff_key() compara dois ou mais arrays pelas suas chaves e retorna as entradas do primeiro array cujas chaves não estão presentes em nenhum dos outros arrays. A palavra-chave é chaves: a função nunca analisa os valores. Isso a torna a ferramenta certa sempre que você deseja remover ou manter elementos de um array com base em um conjunto de chaves — por exemplo, eliminar campos indesejados de dados de formulário ou identificar quais opções de configuração estão ausentes de uma substituição.

Esta página abrange a assinatura da função, um exemplo executável, como ela trata valores e chaves numéricas, os casos de uso mais comuns no mundo real e como ela difere das funções relacionadas de comparação de arrays.

Sintaxe

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

• $array — o array a ser comparado (o resultado só contém entradas deste array).
• ...$arrays — um ou mais arrays cujas chaves são usadas para excluir entradas de $array.
• Retorna um novo array. Cada entrada de $array é mantida somente se sua chave não aparecer em nenhum dos outros arrays. Chaves e valores são preservados exatamente como estavam em $array.

Como o array_diff_key Funciona

A função percorre as chaves do primeiro array. Para cada chave, ela verifica todos os outros arrays; se a chave for encontrada em qualquer um deles, a entrada é descartada. Apenas as entradas cujas chaves são exclusivas do primeiro array sobrevivem.

Veja um exemplo prático — comparando uma lista completa de preços com os itens que já têm desconto, para encontrar os itens que ainda precisam de um:

Exemplo PHP de uso do 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);

?>

A saída mantém apple e cherry porque suas chaves estão ausentes em $discounted. Observe que banana e date são removidos mesmo que seus valores sejam diferentes entre os dois arrays — array_diff_key() ignora os valores completamente:

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

Comparando mais de dois arrays

Você pode passar qualquer número de arrays. Uma entrada é removida se sua chave aparecer em qualquer um deles:

<?php

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

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

?>

Apenas size permanece, porque color é correspondido por $b e qty é correspondido por $c:

Array
(
    [size] => M
)

Chaves são comparadas como strings

PHP converte todas as chaves para strings antes de compará-las, portanto, a chave inteira 0 e a chave string "0" são tratadas como a mesma chave. Isso importa quando você mistura chaves numéricas e 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 do array_diff_key

• Lista branca/negra de campos. Remova chaves indesejadas da entrada do usuário: array_diff_key($input, array_flip(['password', 'token'])) remove essas duas chaves independentemente dos seus valores.
• Encontrando configuração ausente. Compare um conjunto de padrões com uma configuração fornecida pelo usuário para ver quais chaves foram omitidas.
• Reconciliando conjuntos de dados. Identifique registros (indexados por ID) que existem em um array mas não em outro.
• Limpando dados de requisição antes de passá-los para uma função que rejeita chaves inesperadas.

Dica: Se você quer manter apenas as entradas cujas chaves aparecem em outro array, use array_intersect_key() — ela é o espelho de array_diff_key().

array_diff_key vs. funções relacionadas

Se você precisar de uma verificação adicional de valor além da comparação de chaves, use array_diff_assoc(). Para personalizar como as chaves são comparadas (por exemplo, correspondência sem diferenciação de maiúsculas e minúsculas), use array_diff_ukey().

Conclusão

array_diff_key() é uma forma focada e rápida de filtrar um array com base nas chaves de outros. Lembre-se das duas regras que confundem as pessoas: ela compara somente chaves (os valores são ignorados) e as chaves são convertidas para strings antes da comparação. Para comparações que consideram os valores, use array_diff_assoc(), e para testar uma única chave use array_key_exists().

Prática