uksort()

Introdução

uksort() ordena um array pelas suas chaves usando uma função de comparação que você mesmo escreve. Ao contrário de ksort(), que ordena as chaves apenas em ordem crescente natural, uksort() permite que você defina a ordem — alfabética, inversa, por comprimento de string, por uma lista de prioridade personalizada, ou qualquer regra que você consiga expressar em código. A associação chave-valor é sempre preservada.

Esta página abrange a sintaxe e o valor de retorno, como a função de comparação (callback) funciona, vários exemplos executáveis (incluindo o operador spaceship), armadilhas comuns e como uksort() difere de funções de ordenação relacionadas.

Sintaxe

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

• $array — o array a ser ordenado. É passado por referência e ordenado in place, portanto a variável original é modificada diretamente.
• $callback — uma função de comparação que recebe duas chaves ($a e $b) e retorna um inteiro:
  • um número negativo se $a deve vir antes de $b,
  • 0 se forem consideradas iguais,
  • um número positivo se $a deve vir depois de $b.

A função retorna true (no PHP 8+; anteriormente retornava um bool). Como a ordenação ocorre por referência, você lê o resultado a partir da variável do array original — não pelo valor de retorno.

O callback compara chaves, não valores. Esse é o fato que distingue uksort() de usort() (que compara valores) e uasort() (que compara valores mas mantém a associação de chaves).

Exemplo básico: ordenar chaves alfabeticamente

Suponha que temos um array de frutas com chaves por nome e queremos que fiquem em ordem alfabética pela chave:

<?php

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

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

uksort($fruits, "cmp");

print_r($fruits);

strcmp() já retorna um inteiro negativo, zero ou positivo, portanto se encaixa diretamente no callback. A saída é ordenada pela chave:

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

Usando o operador spaceship

Desde o PHP 7, o operador spaceship <=> retorna -1, 0 ou 1 para menor, igual ou maior — exatamente o que uksort() espera. Com uma arrow function, o callback se torna uma linha única:

<?php

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

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

print_r($data);

Isso ordena as chaves de forma crescente:

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

Para inverter a ordem, troque os operandos: fn($a, $b) => $b <=> $a.

Uma ordenação personalizada

O verdadeiro poder do uksort() está em ordenar por uma regra que nenhuma função interna oferece — por exemplo, por comprimento de chave, e depois alfabeticamente em caso de empate:

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

O ?: de curto-circuito retorna a comparação por comprimento, a menos que seja 0, caso em que recorre à comparação alfabética:

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

Armadilhas comuns

• Retorna true, não o array ordenado. Escrever $sorted = uksort($arr, ...) lhe dá true. Use $arr depois em vez disso.
• O array original é mutado. Copie-o primeiro ($copy = $arr;) se precisar manter a ordem original.
• O callback deve ser consistente. Retornar valores aleatórios (por exemplo, rand(-1, 1)) gera resultados indefinidos. Para embaralhar, use shuffle() nos valores ou array_rand() nas chaves.
• Retorne um inteiro. Retornar um bool funciona por coerção, mas é frágil — false vira 0 (igual), portanto return $a < $b; é um bug. Use <=> ou strcmp().

Como uksort() se compara a funções relacionadas

Em resumo: use uksort() sempre que precisar ordenar um array associativo pelas suas chaves com uma regra que ksort() não consegue expressar. Para mais informações sobre o tema, veja Ordenando Arrays em PHP.

Conclusão

uksort() ordena um array associativo pelas suas chaves usando um callback de comparação que você controla, modificando o array in place e preservando os vínculos chave-valor. Com o operador spaceship o callback é conciso, e a lógica personalizada permite implementar ordenações que nenhuma função interna oferece.

Diagrama

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];

Prática