uksort — Funktion · PHP-Referenz

Signatur

uksort(array &$array, callable $callback): true

Beschreibung

uksort() sortiert ein Array anhand seiner Schlüssel, wobei die Reihenfolge durch eine benutzerdefinierte Callback-Funktion bestimmt wird. Im Unterschied zu usort() (Vergleich nach Werten) oder ksort() (natürliche Schlüsselsortierung) ermöglicht uksort() eine vollständig individuelle Sortierlogik für die Schlüssel.

Die Callback-Funktion erhält zwei Schlüssel als Parameter und muss einen negativen Integer zurückgeben, wenn der erste Schlüssel vor dem zweiten stehen soll, einen positiven Integer wenn er danach stehen soll, und 0 wenn beide als gleich zu behandeln sind. Der Raumschiff-Operator (<=>) eignet sich hervorragend für kompakte Vergleiche.

Die Funktion arbeitet in-place: Das übergebene Array wird direkt verändert. Die Schlüssel-Wert-Zuordnungen bleiben dabei vollständig erhalten, was uksort() besonders für assoziative Arrays wertvoll macht. Seit PHP 8.0.0 gibt die Funktion stets true zurück.

Typische Einsatzgebiete sind das Sortieren assoziativer Arrays nach benutzerdefinierten Kriterien, z. B. nach Schlüssellänge, nach einem Teil des Schlüssels oder nach einer externen Prioritätsliste.

Parameter

Name	Typ	Default	Beschreibung
$array Pflicht	array		Das zu sortierende Array. Es wird als Referenz übergeben und direkt verändert.
$callback Pflicht	callable		Die Vergleichsfunktion mit der Signatur `callback(mixed $a, mixed $b): int`. Sie erhält zwei Schlüssel und muss einen negativen, null oder positiven Integer zurückgeben, je nachdem ob `$a` kleiner, gleich oder größer als `$b` ist.

Rückgabewert

Typ

true

Beschreibung

Gibt stets true zurück (seit PHP 8.0.0). In älteren PHP-Versionen wurde bei Erfolg true und bei Fehler false zurückgegeben.

Beispiele

Assoziatives Array nach Schlüssellänge sortieren

<?php
$data = [
    'banana'     => 2,
    'kiwi'       => 5,
    'strawberry' => 1,
    'fig'        => 8,
];

uksort($data, function (string $a, string $b): int {
    return strlen($a) <=> strlen($b);
});

foreach ($data as $key => $value) {
    echo "$key => $value\n";
}

fig => 8 kiwi => 5 banana => 2 strawberry => 1

Array nach einer benutzerdefinierten Prioritätsliste sortieren

<?php
$config = [
    'database' => 'mysql',
    'host'     => 'localhost',
    'port'     => 3306,
    'user'     => 'root',
    'password' => 'secret',
];

$priority = ['host', 'port', 'database', 'user', 'password'];

uksort($config, function (string $a, string $b) use ($priority): int {
    $posA = array_search($a, $priority);
    $posB = array_search($b, $priority);
    // Nicht gefundene Schlüssel ans Ende
    $posA = ($posA === false) ? PHP_INT_MAX : $posA;
    $posB = ($posB === false) ? PHP_INT_MAX : $posB;
    return $posA <=> $posB;
});

foreach ($config as $key => $value) {
    echo "$key: $value\n";
}

host: localhost port: 3306 database: mysql user: root password: secret

Schlüssel alphabetisch absteigend sortieren (Kurzform)

<?php
$arr = ['banana' => 1, 'apple' => 2, 'cherry' => 3];

uksort($arr, fn(string $a, string $b): int => $b <=> $a);

print_r($arr);

Array ( [cherry] => 3 [banana] => 1 [apple] => 2 )

// Wichtig · Fallstricke

Stabilität: Seit PHP 8.0.0 ist uksort() stabil, d. h. Elemente mit gleichen Schlüsseln (Vergleich ergibt 0) behalten ihre ursprüngliche Reihenfolge. In früheren PHP-Versionen war die Sortierung instabil.

Konsistenz der Callback-Funktion: Die Vergleichsfunktion muss eine konsistente totale Ordnung definieren – widersprüchliche Vergleiche (z. B. A < B und B < A gleichzeitig) führen zu undefiniertem Sortierverhalten und können endlose Schleifen verursachen.

Für einfache alphabetische Schlüsselsortierung sind ksort() und krsort() effizienter, da sie keinen Callback-Overhead haben.

Siehe auch

usort uasort ksort krsort arsort array_multisort