usort()

A função usort() do PHP ordena um array usando uma função de comparação que você escreve. Enquanto funções embutidas como sort() só sabem ordenar valores de uma forma (ascendente, por valor), usort() permite expressar qualquer regra — ordenar objetos por uma propriedade, números em uma ordem personalizada ou strings com uma regra de desempate. Esta página explica como o callback de comparação funciona, apresenta exemplos com strings, números e objetos, e aborda as armadilhas mais comuns.

O que é a função usort()?

A função usort() é uma função embutida do PHP que ordena um array usando sua própria regra de comparação. Ao contrário das funções de ordenação padrão, que ordenam por valor ou chave em ordem ascendente/descendente, usort() exige um callback para definir a lógica de comparação. Ela modifica o array original no lugar e retorna true em caso de sucesso ou false em caso de falha (ou seja, você ordena o array, mas não captura o valor de retorno como resultado ordenado).

Como o callback de comparação funciona

O callback recebe dois elementos, $a e $b, e deve retornar um inteiro que informa ao usort() a ordem relativa deles:

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

Desde o PHP 7, o operador spaceship <=> faz exatamente isso em um único passo: $a <=> $b retorna -1, 0 ou 1. A maioria dos callbacks de comparação se reduz a um único return usando-o.

Nota: usort() não é uma ordenação estável. Se dois elementos forem considerados iguais, a ordem relativa original não é garantida. A partir do PHP 8.0, a ordenação é estável, mas versões anteriores não garantem isso. Além disso, usort() reindexa o array sequencialmente a partir de 0, então as chaves originais são perdidas — use uasort() se precisar manter as associações de chave.

Sintaxe

A sintaxe da função usort() é a seguinte:

A sintaxe da função usort() em PHP

usort($array, $callback);

Aqui, $array é o array que você deseja ordenar, e $callback é a função de callback que define as regras de ordenação personalizadas.

Parâmetros e Valor de Retorno

Valor de Retorno: Retorna true em caso de sucesso ou false em caso de falha.

Exemplo de Uso

Vejamos um exemplo para entender como a função usort() funciona. Suponha que temos um array de nomes que queremos ordenar em ordem alfabética, mas com uma regra personalizada em que todos os nomes começando com "J" devem vir primeiro.

Como usar a função usort() em PHP?

Neste exemplo, definimos uma função de callback que compara dois nomes e retorna -1, 0 ou 1 com base nas regras de ordenação personalizadas. Se a primeira letra de $a for "J" e a primeira letra de $b não for "J", então $a vem antes de $b. Se a primeira letra de $a não for "J" e a primeira letra de $b for "J", então $b vem antes de $a. Se ambos os nomes começarem com "J" ou nenhum deles começar com "J", usamos o operador spaceship moderno do PHP (<=>) para comparar os nomes alfabeticamente.

Após executar este código, o array $names será ordenado da seguinte forma:

Array
(
    [0] => Jack
    [1] => Jenny
    [2] => John
    [3] => Adam
    [4] => Bob
)

Ordenando objetos ou arrays por um campo

O uso mais comum de usort() no mundo real é ordenar uma lista de registros (arrays associativos ou objetos) por um de seus campos — algo que sort() não consegue fazer. Aqui ordenamos uma lista de produtos por preço, de forma ascendente:

<?php

$products = [
    ["name" => "Book",   "price" => 15],
    ["name" => "Pen",    "price" => 2],
    ["name" => "Laptop", "price" => 900],
];

usort($products, fn ($a, $b) => $a["price"] <=> $b["price"]);

print_r(array_column($products, "name"));

Toda a comparação é uma única expressão spaceship. A saída, do mais barato para o mais caro:

Array
(
    [0] => Pen
    [1] => Book
    [2] => Laptop
)

Para ordenar de forma descendente, basta inverter os operandos: $b["price"] <=> $a["price"].

Armadilhas comuns

• Uso incorreto do valor de retorno. usort() retorna true/false, não o array ordenado. Escrever $sorted = usort($arr, ...) retorna true, não seus dados. O array é ordenado no lugar.
• As chaves são redefinidas. As chaves originais são descartadas e substituídas por 0, 1, 2, …. Use uasort() para preservar as chaves, ou uksort() para ordenar pelas chaves.
• Retornar um boolean no callback. Retornar $a > $b (um boolean) funciona acidentalmente para ordem ascendente, mas falha para ordem descendente e casos de igualdade. Sempre retorne um inteiro — prefira <=>.

Funções relacionadas

• sort() — ordena um array por valor, de forma ascendente, sem callback.
• asort() — ordena por valor preservando as chaves.
• ksort() — ordena por chave.
• uasort() — como usort(), mas preserva as associações de chave.
• uksort() — ordena pelas chaves usando um callback personalizado.

Conclusão

Neste artigo, discutimos a função usort() em PHP e demonstramos como ela pode ser usada para ordenar arrays com regras de ordenação personalizadas. Ao definir uma função de callback, você pode ordenar arrays em qualquer ordem desejada, com base em suas próprias regras. Essa função pode ser especialmente útil em situações em que as funções de ordenação embutidas do PHP não são suficientes para suas necessidades. Com a função usort(), você tem controle completo sobre como seus arrays são ordenados.

Prática