Comprendre la fonction PHP array_diff_key

array_diff_key() compare deux tableaux ou plus par leurs clés et retourne les entrées du premier array dont les clés sont absentes de tous les autres tableaux. Le mot clé ici est clés : la fonction n'examine jamais les valeurs. C'est donc l'outil idéal lorsque vous souhaitez supprimer ou conserver des éléments d'un array en fonction d'un ensemble de clés — par exemple, pour supprimer des champs indésirables d'une saisie de formulaire ou pour identifier les options de configuration manquantes dans une substitution.

Cette page couvre la signature de la fonction, un exemple exécutable, la façon dont elle traite les valeurs et les clés numériques, les cas d'utilisation les plus courants, ainsi que ses différences avec les fonctions de comparaison d'arrays apparentées.

Syntaxe

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

• $array — le tableau à comparer (le résultat ne contient jamais que ses entrées).
• ...$arrays — un ou plusieurs tableaux dont les clés servent à exclure des entrées de $array.
• Retourne un nouvel array. Chaque entrée de $array est conservée uniquement si sa clé n'apparaît dans aucun des autres tableaux. Les clés et les valeurs sont préservées exactement telles qu'elles étaient dans $array.

Fonctionnement de array_diff_key

La fonction parcourt les clés du premier tableau. Pour chaque clé, elle vérifie tous les autres tableaux ; si la clé est trouvée quelque part, cette entrée est supprimée. Seules les entrées dont les clés sont uniques au premier tableau survivent.

Voici un exemple pratique — comparer une liste de prix complète avec les articles ayant déjà une remise, afin de trouver ceux qui en ont encore besoin :

Exemple PHP d'utilisation 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);

?>

Le résultat conserve apple et cherry car leurs clés sont absentes de $discounted. Notez que banana et date sont supprimés même si leurs valeurs diffèrent entre les deux tableaux — array_diff_key() ignore totalement les valeurs :

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

Comparer plus de deux tableaux

Vous pouvez passer un nombre quelconque de tableaux. Une entrée est supprimée si sa clé apparaît dans l'un quelconque d'entre eux :

<?php

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

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

?>

Seule size reste, car color est trouvée dans $b et qty dans $c :

Array
(
    [size] => M
)

Les clés sont comparées en tant que strings

PHP convertit toutes les clés en strings avant de les comparer, de sorte que la clé entière 0 et la clé string "0" sont traitées comme la même clé. Cela importe lorsque vous mélangez des clés numériques et des clés string :

<?php

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

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

?>

Array
(
    [1] => b
)

Cas d'utilisation de array_diff_key

• Liste blanche/liste noire de champs. Supprimez les clés indésirables de la saisie utilisateur : array_diff_key($input, array_flip(['password', 'token'])) retire ces deux clés quelle que soit leur valeur.
• Identification des configurations manquantes. Comparez un ensemble de valeurs par défaut avec une configuration fournie par l'utilisateur pour voir quelles clés ont été omises.
• Réconciliation de jeux de données. Identifiez les enregistrements (indexés par ID) qui existent dans un array mais pas dans un autre.
• Nettoyage des données de requête avant de les passer à une fonction qui rejette les clés inattendues.

Conseil : Si vous souhaitez au contraire conserver uniquement les entrées dont les clés apparaissent dans un autre array, utilisez array_intersect_key() — c'est l'image miroir de array_diff_key().

array_diff_key vs. fonctions apparentées

Si vous avez besoin d'une vérification supplémentaire des valeurs en plus de la comparaison par clés, utilisez array_diff_assoc(). Pour personnaliser la manière dont les clés sont comparées (par exemple, une correspondance insensible à la casse), utilisez array_diff_ukey().

Conclusion

array_diff_key() est un moyen ciblé et rapide de filtrer un array selon les clés d'autres tableaux. Retenez les deux règles qui piègent souvent les développeurs : elle compare les clés uniquement (les valeurs sont ignorées), et les clés sont converties en strings avant la comparaison. Pour des comparaisons tenant compte des valeurs, consultez array_diff_assoc(), et pour tester une clé unique, utilisez array_key_exists().

Pratique