uksort()

Introduzione

uksort() ordina un array per chiavi usando una funzione di confronto che scrivi tu stesso. A differenza di ksort(), che ordina le chiavi solo in modo ascendente naturale, uksort() ti permette di decidere l'ordine — alfabetico, inverso, per lunghezza della stringa, in base a una lista di priorità personalizzata, o qualsiasi regola esprimibile in codice. L'associazione chiave-valore è sempre preservata.

Questa pagina illustra la sintassi e il valore restituito, come funziona la callback di confronto, diversi esempi eseguibili (incluso l'operatore spaceship), le insidie comuni e le differenze tra uksort() e le funzioni di ordinamento correlate.

Sintassi

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

• $array — l'array da ordinare. Viene passato per riferimento e ordinato in-place, quindi la variabile originale viene modificata direttamente.
• $callback — una funzione di confronto che riceve due chiavi ($a e $b) e restituisce un intero:
  • un numero negativo se $a deve venire prima di $b,
  • 0 se sono considerate uguali,
  • un numero positivo se $a deve venire dopo $b.

La funzione restituisce true (in PHP 8+; in precedenza restituiva un bool). Poiché l'ordinamento avviene per riferimento, si legge il risultato dalla variabile array originale — non dal valore restituito.

La callback confronta le chiavi, non i valori. Questa è la differenza fondamentale tra uksort() e usort() (che confronta i valori) e uasort() (che confronta i valori ma mantiene l'associazione delle chiavi).

Esempio di base: ordinare le chiavi alfabeticamente

Supponiamo di avere un array di frutti con chiave per nome e di volerli in ordine alfabetico per chiave:

<?php

$fruits = [
    "orange" => 3,
    "apple"  => 2,
    "banana" => 1,
];

function cmp($a, $b)
{
    return strcmp($a, $b);
}

uksort($fruits, "cmp");

print_r($fruits);

strcmp() restituisce già un intero negativo, zero o positivo, quindi si adatta perfettamente alla callback. L'output è ordinato per chiave:

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

Usare l'operatore spaceship

Da PHP 7, l'operatore spaceship <=> restituisce -1, 0 o 1 per minore di, uguale o maggiore di — esattamente il formato atteso da uksort(). Con una arrow function la callback diventa una singola riga:

<?php

$data = ["delta" => 1, "alpha" => 2, "charlie" => 3, "bravo" => 4];

uksort($data, fn($a, $b) => $a <=> $b);

print_r($data);

Questo ordina le chiavi in modo ascendente:

Array
(
    [alpha] => 2
    [bravo] => 4
    [charlie] => 3
    [delta] => 1
)

Per invertire l'ordine, scambia gli operandi: fn($a, $b) => $b <=> $a.

Un ordinamento personalizzato

La vera potenza di uksort() è l'ordinamento secondo una regola che nessuna funzione built-in fornisce — ad esempio, per lunghezza della chiave, poi alfabeticamente in caso di parità:

<?php

$config = [
    "id"          => 1,
    "name"        => "Ann",
    "is_active"   => true,
    "x"           => 0,
];

uksort($config, function ($a, $b) {
    return strlen($a) <=> strlen($b)   // shortest keys first
        ?: strcmp($a, $b);             // ties broken alphabetically
});

print_r($config);

L'operatore ?: in short-circuit restituisce il confronto per lunghezza a meno che non sia 0, nel qual caso ricade nel confronto alfabetico:

Array
(
    [x] => 0
    [id] => 1
    [name] => Ann
    [is_active] => 1
)

Insidie comuni

• Restituisce true, non l'array ordinato. Scrivere $sorted = uksort($arr, ...) ti dà true. Usa $arr in seguito.
• L'array originale viene modificato. Copialo prima ($copy = $arr;) se hai bisogno di mantenere l'ordine originale.
• La callback deve essere coerente. Restituire valori casuali (es. rand(-1, 1)) produce risultati non definiti. Per mescolare, usa shuffle() sui valori o array_rand() sulle chiavi.
• Restituisci un intero. Restituire un bool funziona per coercizione ma è fragile — false diventa 0 (uguale), quindi return $a < $b; è un bug. Usa <=> o strcmp().

Come uksort() si confronta con le funzioni correlate

In sintesi: scegli uksort() ogni volta che hai bisogno di ordinare un array associativo per chiavi con una regola che ksort() non può esprimere. Per approfondire l'argomento, consulta Ordinare Array in PHP.

Conclusione

uksort() ordina un array associativo per chiavi usando una callback di confronto che controlli tu, modificando l'array in-place e preservando i legami chiave-valore. Con l'operatore spaceship la callback è concisa, e la logica personalizzata permette di implementare ordinamenti che nessuna funzione built-in offre.

Diagramma

graph LR
A[Array] --> B(Function);
B --> C[Comparison result];
C --> D{Is result negative?};
D -->|Yes| E[Swap];
C -->|No| F[Do not swap];
F --> G[Next comparison];
E --> G[Next comparison];

Pratica