uasort()

Ordenando Arrays em PHP com uasort()

A função PHP uasort() ordena um array associativo pelos seus valores usando uma função de comparação que você mesmo escreve, mantendo cada valor associado à sua chave original. O "u" representa user-defined (você fornece a lógica de comparação) e o "a" representa associative (os pares chave/valor são preservados).

Esta página aborda o que uasort() faz, sua sintaxe, como escrever uma função de comparação correta e exemplos práticos para arrays simples, associativos e multidimensionais — cada resultado mostrado é a saída real da execução do código.

O que uasort() faz e quando usá-la

A maioria das funções de ordenação do PHP ignora as chaves ou permite apenas ordenar pelas regras de comparação embutidas. uasort() oferece as duas coisas ao mesmo tempo:

• Você controla a ordem. Você passa um callback que decide qual de dois valores vem primeiro, então pode ordenar por comprimento, por um campo aninhado, em ordem reversa, por uma lista de prioridade personalizada — qualquer coisa que você possa expressar em código.
• As chaves permanecem com seus valores. Após a ordenação, $array["John"] ainda aponta para o valor de John; apenas a ordem em que os pares são iterados muda.

Use uasort() quando ambas as condições forem verdadeiras: você precisa de uma regra personalizada e as chaves são significativas (um nome, um ID, um slug). Se as chaves são apenas posições descartáveis 0, 1, 2…, usort() é mais simples porque reindexará para você. Se você quiser ordenar pelas chaves em vez dos valores, use uksort(). Se você precisar apenas de uma ordenação simples de valores ascendente/descendente sem regra personalizada, asort() e arsort() fazem isso sem callback.

Sintaxe

uasort(array &$array, callable $callback): bool

• array &$array — o array a ser ordenado. O & significa que é passado por referência: uasort() ordena o array no local e retorna true/false, não retorna um novo array ordenado.
• callable $callback — sua função de comparação. Ela recebe dois valores, $a e $b, e deve retornar um inteiro indicando a ordem relativa deles ao PHP.
• Valor de retorno — bool, sempre true (retorna um valor para poder ser usado em expressões, mas normalmente você a chama pelo efeito colateral em $array).

Como o array é modificado no local, escreva uasort($array, ...); em sua própria linha — não escreva $array = uasort($array, ...), o que sobrescreveria seus dados com true.

Escrevendo a função de comparação

O callback compara dois valores e retorna um inteiro:

• um número negativo se $a deve vir antes de $b,
• 0 se a ordem não importa (eles são considerados iguais),
• um número positivo se $a deve vir depois de $b.

A maneira mais limpa de produzir isso é o operador spaceship <=>, que retorna exatamente -1, 0 ou 1:

// ascending
fn($a, $b) => $a <=> $b;

// descending — just flip the operands
fn($a, $b) => $b <=> $a;

O estilo mais antigo ($a < $b) ? -1 : 1 também funciona, mas nunca retorna 0, então elementos iguais recebem uma ordem arbitrária. Prefira <=>; é mais curto, correto para o caso de igualdade e funciona para números, strings e arrays.

Exemplo 1: Ordenando valores de um array indexado (chaves preservadas)

Aqui uasort() ordena os números em ordem ascendente, mas observe que as chaves originais viajam com os valores — essa é a diferença em relação a sort(), que os renumeraria 0…9.

Saída:

Array
(
    [1] => 1
    [3] => 1
    [6] => 2
    [0] => 3
    [9] => 3
    [2] => 4
    [4] => 5
    [8] => 5
    [7] => 6
    [5] => 9
)

Exemplo 2: Ordenando um array associativo por valor

Este é o uso mais comum: ordenar pessoas por idade mantendo seus nomes como chaves.

Saída:

Array
(
    [Mary] => 28
    [Jane] => 28
    [John] => 32
    [David] => 37
    [Bob] => 45
)

Para ordenar do mais velho ao mais novo, inverta os operandos: fn($a, $b) => $b <=> $a.

Exemplo 3: Ordenando um array multidimensional por um campo aninhado

Quando cada elemento é em si um array, o callback recebe o sub-array inteiro, então você o indexa para escolher o campo de ordenação. Aqui ordenamos por idade ([1]).

Saída:

Array
(
    [1] => Array
        (
            [0] => Mary
            [1] => 28
        )

    [3] => Array
        (
            [0] => Jane
            [1] => 28
        )

    [0] => Array
        (
            [0] => John
            [1] => 32
        )

    [4] => Array
        (
            [0] => David
            [1] => 37
        )

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

)

Para linhas com chave por um campo associativo, substitua $a[1] por algo como $a['age'].

uasort() vs usort()

As funções são idênticas exceto pelas chaves. Execute os mesmos dados nas duas:

<?php

$ages = ["John" => 32, "Mary" => 28, "Bob" => 45];

$copy = $ages;
usort($copy, fn($a, $b) => $a <=> $b);
echo "usort (keys lost):\n";
print_r($copy);

uasort($ages, fn($a, $b) => $a <=> $b);
echo "uasort (keys kept):\n";
print_r($ages);

Saída:

usort (keys lost):
Array
(
    [0] => 28
    [1] => 32
    [2] => 45
)
uasort (keys kept):
Array
(
    [Mary] => 28
    [John] => 32
    [Bob] => 45
)

Armadilhas comuns

• Retorna true, não o array. Leia o resultado ordenado a partir da variável que você passou, não do valor de retorno.
• A ordenação não é estável antes do PHP 8.0. Se dois valores forem iguais, a ordem relativa deles era definida pela implementação em versões mais antigas. Desde o PHP 8.0, todas as funções de ordenação (incluindo uasort()) são estáveis, então elementos iguais mantêm sua ordem original.
• Sempre trate o caso de igualdade. Retornar 1 para "não menor que" (em vez de 0) pode embaralhar elementos iguais no PHP antigo e simplesmente está incorreto; <=> lida com isso automaticamente.

Funções relacionadas

• usort() — mesma ordenação com regra personalizada, mas reindexar as chaves.
• uksort() — ordenar pelas chaves com um callback personalizado.
• asort() / arsort() — ordenação por valor, ascendente/descendente, sem necessidade de callback.
• ksort() — ordenar por chaves sem callback.
• Ordenando arrays em PHP — visão geral de cada função de ordenação e quando usar cada uma.

Conclusão

uasort() é a ferramenta para ordenar um array associativo por valor com sua própria regra de comparação, mantendo as chaves intactas. Combine-a com o operador spaceship para callbacks limpos e corretos, lembre-se de que ela ordena no local e escolha-a em vez de usort() sempre que as chaves tiverem significado.

Prática