Comprendre la fonction array_udiff() de PHP

array_udiff() calcule la différence entre des tableaux en comparant leurs valeurs à l'aide d'une fonction de rappel que vous fournissez. Elle retourne les valeurs présentes dans le premier tableau qui ne se trouvent dans aucun des autres tableaux. Le « u » dans le nom signifie user-defined (défini par l'utilisateur) — contrairement à array_diff(), qui compare les valeurs en tant que string, array_udiff() vous permet de décider exactement quand deux valeurs sont considérées comme « égales ».

Cette page couvre la syntaxe de la fonction, le fonctionnement du callback, des exemples exécutables avec des nombres et des objets, ainsi que les pièges courants à éviter.

Quand utiliser array_udiff() ?

Utilisez array_udiff() chaque fois que la comparaison par défaut de array_diff() est trop grossière :

• Objets. array_diff() convertit chaque valeur en string. Les objets sans méthode __toString() ne peuvent pas être comparés de cette façon ; vous avez donc besoin d'un callback qui inspecte une propriété à la place.
• Égalité personnalisée. Vous souhaitez une comparaison insensible à la casse, une comparaison sur un seul champ, ou une comparaison numérique avec tolérance.
• Données mixtes ou normalisées. Vous voulez traiter "5", 5 et 5.0 comme la même valeur, ou comparer des flottants avec arrondi.

Si vous n'avez besoin que d'une comparaison de string simple, préférez array_diff().

Comment fonctionne array_udiff()

La fonction prend deux tableaux ou plus, le dernier argument étant le callback de comparaison. Elle retourne un array des valeurs du premier tableau que le callback ne considère égales à aucune valeur des tableaux suivants. Les clés et l'ordre du premier tableau sont préservés.

Syntaxe

array_udiff(array $array1, array $array2, array ...$arrays, callable $value_compare_func): array

• array $array1 — le tableau dont les valeurs sont retournées (le tableau « de base »).
• array $array2 — un tableau auquel comparer.
• array ...$arrays — un nombre quelconque de tableaux supplémentaires à comparer.
• callable $value_compare_func — le callback de comparaison. C'est toujours le dernier argument.

Le callback de comparaison

Le callback reçoit deux valeurs et doit retourner un entier :

• un nombre inférieur à 0 si la première valeur est « plus petite »,
• 0 si les deux valeurs sont considérées comme égales,
• un nombre supérieur à 0 si la première valeur est « plus grande ».

Retourner 0 marque deux valeurs comme égales ; ainsi, une valeur de $array1 est exclue du résultat chaque fois que le callback retourne 0 pour elle face à une valeur d'un tableau ultérieur. Les résultats < 0 / > 0 permettent à PHP de trier les valeurs en interne pour une comparaison efficace — les obtenir correctement est important, donc ne retournez pas simplement 0 ou 1. L'opérateur spaceship (<=>) est la façon la plus simple et correcte de produire cette valeur.

Exemple 1 : comparer deux tableaux de nombres

Cet exemple utilise une fonction nommée comme callback pour trouver les nombres présents dans $array1 mais pas dans $array2 :

<?php

function compare_numbers($a, $b) {
    if ($a == $b) {
        return 0;
    } elseif ($a < $b) {
        return -1;
    } else {
        return 1;
    }
}

$array1 = [1, 2, 3, 4, 5];
$array2 = [2, 4, 6];

$result = array_udiff($array1, $array2, 'compare_numbers');

print_r($result);

?>

compare_numbers() retourne 0 chaque fois que deux valeurs correspondent, donc les nombres correspondants (2 et 4) sont supprimés. Le résultat conserve les clés d'origine de $array1 :

Array
(
    [0] => 1
    [2] => 3
    [4] => 5
)

L'intégralité du callback pourrait être remplacée par une seule ligne utilisant l'opérateur spaceship : fn($a, $b) => $a <=> $b.

Exemple 2 : comparer des tableaux d'objets

C'est le cas que array_diff() ne peut pas gérer. Ici, nous comparons deux tableaux d'objets Product par leur id, en retournant les produits qui ne figurent pas dans la deuxième liste :

<?php

class Product {
    public function __construct(public int $id, public string $name) {}
}

$catalog = [
    new Product(1, 'Keyboard'),
    new Product(2, 'Mouse'),
    new Product(3, 'Monitor'),
];

$discontinued = [
    new Product(2, 'Mouse'),
];

$available = array_udiff(
    $catalog,
    $discontinued,
    fn(Product $a, Product $b) => $a->id <=> $b->id
);

foreach ($available as $product) {
    echo $product->id . ': ' . $product->name . PHP_EOL;
}

?>

Cela affiche les produits dont l'id n'est pas présent dans $discontinued :

1: Keyboard
3: Monitor

Comme le callback compare uniquement l'id, les valeurs différentes de name sont sans importance — la logique de comparaison est entièrement à votre définition.

Points importants à garder à l'esprit

• Le callback est toujours le dernier argument, quel que soit le nombre de tableaux passés.
• array_udiff() compare les valeurs. Pour comparer à la fois les clés et les valeurs, utilisez array_udiff_assoc() ; pour comparer aussi les clés avec un callback, utilisez array_udiff_uassoc().
• Retournez un résultat ternaire correct (négatif / 0 / positif), pas seulement 0 ou 1. PHP s'appuie sur l'ordre pour comparer efficacement, et un callback approximatif peut produire des résultats incorrects.
• Le résultat préserve les clés et l'ordre de $array1. Appelez array_values() si vous souhaitez un array réindexé.
• Seules les valeurs du premier tableau peuvent apparaître dans la sortie — les valeurs uniques aux tableaux suivants ne sont jamais retournées.

Fonctions associées

• array_diff() — la même idée avec une comparaison de string simple.
• array_udiff_assoc() — callback sur les valeurs et comparaison des clés.
• array_uintersect() — l'équivalent pour l'intersection (valeurs présentes dans tous les tableaux).
• PHP Arrays et PHP Functions pour les fondamentaux.

Pratique