PHP Reference ยท Array Functions
PHP usort(), uasort() and uksort() functions
Reference for PHP usort(), uasort() and uksort(): sort arrays with your own comparison callback, the spaceship operator, multi-field sorting and key handling.
usort(), uasort() and uksort() sort an array with a comparison function you write. They are the tools for any order the built-in flags cannot express: sort records by a field, by several fields, by length, or by a custom ranking.
The three differ in what they compare and what they do with keys. usort() compares values and re-indexes the array. uasort() compares values and keeps the keys. uksort() compares keys and keeps them. All three work in place and return true.
<?php $words = ["fig", "banana", "kiwi"]; usort($words, fn($a, $b) => strlen($a) <=> strlen($b));
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.
Syntax
usort(array &$array, callable $callback): true uasort(array &$array, callable $callback): true uksort(array &$array, callable $callback): true
| Name | Description |
|---|---|
$array |
The array to sort, passed by reference. |
$callback |
function ($a, $b): int. Return a negative number if $a comes first, a positive number if $b comes first and 0 if they are equal. For uksort() the arguments are keys. |
Return value: always true in PHP 8.2 and later.
Usage notes
- Use the spaceship operator.
$a <=> $breturns exactly-1,0or1. Subtracting ($a - $b) works for small integers but breaks for floats, because the return value is cast to an integer. - Never return a boolean.
fn($a, $b) => $a > $breturnstrueorfalse, never a negative number. Since PHP 8.0 the sort still comes out right through a compatibility fallback, but it prints aDeprecated: Returning bool from comparison function is deprecatedmessage, as the second example shows. Write<=>instead. - Arrays compare element by element with
<=>, which makes multi-field sorts short:[$a->last, $a->first] <=> [$b->last, $b->first]. Swap the sides of a field to sort it descending. - Stable since PHP 8.0. Items the callback calls equal keep their original order, so you can sort in several passes.
- Keys:
usort()discards them,uasort()anduksort()keep them. Choose by whether the keys carry meaning. - Any callable works, including
strcmp,strnatcasecmp, a static method string or a first-class callable likestrcmp(...). - Performance. The callback runs about n log n times. Compute expensive keys once with
array_map()and usearray_multisort()when the data set is large. - Do not modify the array being sorted inside the callback.