array_udiff — Funktion · PHP-Referenz

Signatur

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

Beschreibung

array_udiff() ermittelt alle Elemente des ersten Arrays, die in keinem der weiteren übergebenen Arrays vorkommen. Anders als array_diff() verwendet diese Funktion keine interne String-Konvertierung für den Vergleich, sondern ruft eine benutzerdefinierte Callback-Funktion auf, die zwei Werte miteinander vergleicht.

Die Callback-Funktion muss nach dem üblichen Komparator-Prinzip arbeiten: Sie gibt eine negative Zahl zurück, wenn das erste Argument kleiner als das zweite ist, 0 wenn beide gleich sind, und eine positive Zahl wenn das erste Argument größer ist. Nur Elemente, für die die Callback-Funktion niemals 0 zurückgibt (d. h. die in keinem anderen Array als gleich erkannt werden), erscheinen im Ergebnis.

Die Funktion ist besonders nützlich, wenn Arrays von Objekten oder komplexen Datenstrukturen verglichen werden sollen, bei denen der Standard-String-Vergleich nicht ausreicht – z. B. beim Vergleich von Objekten nach einem bestimmten Attribut oder bei sprachsensitiven (locale-abhängigen) Vergleichen.

Die Schlüssel des ersten Arrays bleiben im Ergebnis erhalten. Es werden nur Werte verglichen, keine Schlüssel. Sollen auch Schlüssel verglichen werden, ist array_udiff_assoc() die geeignetere Funktion.

Parameter

Name	Typ	Beschreibung
$array Pflicht	array	Das Ausgangs-Array, aus dem die Differenz berechnet wird.
$arrays Pflicht	array	Ein oder mehrere Arrays, mit denen das Ausgangs-Array verglichen wird. Es muss mindestens ein weiteres Array angegeben werden.
$value_compare_func Pflicht	callable	Eine Callback-Funktion mit der Signatur `callback(mixed $a, mixed $b): int`. Sie muss eine negative Zahl, `0` oder eine positive Zahl zurückgeben, je nachdem ob `$a` kleiner als, gleich oder größer als `$b` ist. Der Spaceship-Operator `<=>` ist hierfür ideal geeignet.

Rückgabewert

Typ

array

Beschreibung

Gibt ein Array zurück, das alle Elemente aus dem ersten Array enthält, die in keinem der weiteren Arrays gefunden wurden (gemäß der Callback-Funktion). Die ursprünglichen Schlüssel bleiben erhalten. Gibt ein leeres Array zurück, wenn alle Elemente in den Vergleichs-Arrays vorhanden sind.

Beispiele

Einfacher numerischer Vergleich zweier Arrays

<?php
$a = [1, 2, 3, 4, 5];
$b = [3, 4, 5, 6, 7];

$differenz = array_udiff($a, $b, function (int $x, int $y): int {
    return $x <=> $y;
});

print_r($differenz);

Array ( [0] => 1 [1] => 2 )

Differenz von Objekt-Arrays anhand eines Attributs

<?php
class Produkt {
    public function __construct(
        public string $name,
        public int    $id
    ) {}
}

$lager = [
    new Produkt('Apfel',  1),
    new Produkt('Banane', 2),
    new Produkt('Kirsche', 3),
];

$bestellung = [
    new Produkt('Banane', 2),
    new Produkt('Kirsche', 3),
];

$nichtBestellt = array_udiff(
    $lager,
    $bestellung,
    fn(Produkt $a, Produkt $b): int => $a->id <=> $b->id
);

foreach ($nichtBestellt as $p) {
    echo $p->name . PHP_EOL;
}

Apfel

Sprachsensitiver String-Vergleich mit strcoll

<?php
$alle    = ['Äpfel', 'Orangen', 'Birnen', 'Kirschen'];
$vorhanden = ['Orangen', 'Kirschen'];

$fehlend = array_udiff($alle, $vorhanden, 'strcoll');

print_r($fehlend);

Array ( [0] => Äpfel [2] => Birnen )

// Wichtig · Fallstricke

Reihenfolge des letzten Parameters: Die Callback-Funktion muss zwingend als letztes Argument übergeben werden, nach allen zu vergleichenden Arrays. Ein häufiger Fehler ist, die Callback-Funktion an falscher Position zu übergeben, was zu einem TypeError führt.

Performance: Zum internen Sortieren und Vergleichen ruft PHP die Callback-Funktion mehrfach auf. Die Callback-Funktion sollte daher frei von Seiteneffekten und möglichst effizient sein. Bei sehr großen Arrays kann die Laufzeit im Vergleich zu array_diff() (mit eingebautem String-Vergleich) deutlich höher ausfallen.

Schlüsselerhalt: Die Schlüssel des ersten Arrays bleiben im Ergebnis erhalten. Bei numerisch indizierten Arrays kann das zu nicht-kontinuierlichen Schlüsseln im Ergebnis führen. Ggf. array_values() nachschalten, wenn fortlaufende Indizes benötigt werden.

Siehe auch

array_diff array_diff_key array_udiff_assoc array_udiff_uassoc array_uintersect array_intersect