Comprendre la fonction array_intersect_ukey() en PHP

La fonction array_intersect_ukey() compare les clés de deux tableaux ou plus à l'aide d'un callback que vous fournissez, et retourne les entrées du premier tableau dont les clés sont présentes dans tous les autres tableaux. Le u dans le nom signifie comparaison fournie par l'utilisateur — c'est la variante sensible aux clés de array_intersect_key(), la différence étant que vous décidez quand deux clés sont considérées comme « identiques ».

Cette page explique ce que la fonction retourne, comment le callback de comparaison influence le résultat, et les pièges à connaître avant de l'utiliser.

Quand l'utiliser ?

Utilisez array_intersect_ukey() lorsque vous souhaitez ne conserver que les entrées dont les clés se chevauchent, mais qu'une simple égalité de clés ne suffit pas. Cas typiques :

• Correspondance de clés insensible à la casse — traiter Host et host comme la même clé.
• Clés normalisées — ignorer les espaces, les préfixes ou les différences de formatage avant la comparaison.
• Filtrage d'un tableau de configuration ou de requête pour ne garder que les clés présentes dans une liste blanche de clés autorisées.

Si vous n'avez besoin que d'une correspondance exacte des clés, utilisez plutôt le built-in plus simple array_intersect_key() — aucun callback n'est requis.

Syntaxe

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

Paramètres et valeur de retour

Retourne : Un tableau contenant toutes les paires clé-valeur de $array1 dont la clé correspond à une clé dans tous les autres tableaux. Une clé correspond lorsque le callback retourne 0.

Remarque : les valeurs proviennent uniquement de $array1. Les valeurs stockées sous les clés correspondantes dans les autres tableaux sont ignorées — seules leurs clés importent.

Exemple de base

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

?>

Résultat :

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

Le callback compare les clés comme le fait l'opérateur spaceship : il retourne 0 uniquement lorsque deux clés sont égales. Les clés b et red existent dans les deux tableaux, donc leurs entrées sont conservées — avec les valeurs de $array1 (brown et 3), et non de $array2.

En PHP moderne, vous pouvez remplacer tout ce helper par l'opérateur 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);

?>

Résultat :

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

Correspondance de clés insensible à la casse

C'est là que le callback prend tout son sens. strcasecmp() retourne déjà l'entier attendu par la fonction (0 en cas d'égalité, sans tenir compte de la casse), vous pouvez donc le passer directement pour faire correspondre des clés quelle que soit leur capitalisation :

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

?>

Résultat :

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

Host correspond à host et PORT correspond à port même si leur casse diffère, donc les deux survivent. Debug n'a pas de correspondant dans $defaults, il est donc supprimé. Notez que les clés et valeurs conservées sont exactement telles qu'elles sont écrites dans le premier tableau.

Pièges à éviter

• Le callback doit retourner 0 pour une correspondance. Une erreur courante consiste à écrire un callback qui retourne un boolean ($k1 === $k2). true/false sont castés en 1/0, ce qui ferait « correspondre » accidentellement des clés inégales. Retournez toujours un entier de comparaison à trois valeurs.
• Les valeurs proviennent uniquement du premier tableau. Si deux tableaux partagent une clé mais ont des valeurs différentes, le résultat conserve la valeur du premier tableau.
• Le callback est le dernier argument, même lorsque vous passez trois tableaux ou plus à comparer.
• Pour comparer à la fois les clés et les valeurs, voir array_intersect_uassoc() ; pour l'opération inverse (les clés qui ne sont pas partagées), voir array_diff_ukey().

Conclusion

array_intersect_ukey() filtre un tableau pour ne garder que les entrées dont les clés apparaissent également dans tous les autres tableaux, en utilisant votre propre définition de l'égalité des clés. Utilisez-la pour une correspondance de clés insensible à la casse ou normalisée ; revenez à array_intersect_key() lorsqu'une correspondance exacte suffit. La règle essentielle à retenir : le callback doit retourner 0 pour des clés égales, et les valeurs résultantes proviennent toujours du premier tableau.

Exercice