Skip to content
Tutorials Center
My learning

Topics

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
<?php
$words = ["fig", "banana", "kiwi"];
usort($words, fn($a, $b) => strlen($a) <=> strlen($b));

Try it

PHP Sorting records by a field

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.

PHP Keeping keys with uasort and uksort

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

PHP
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 <=> $b returns exactly -1, 0 or 1. 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 > $b returns true or false, never a negative number. Since PHP 8.0 the sort still comes out right through a compatibility fallback, but it prints a Deprecated: Returning bool from comparison function is deprecated message, 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() and uksort() keep them. Choose by whether the keys carry meaning.
  • Any callable works, including strcmp, strnatcasecmp, a static method string or a first-class callable like strcmp(...).
  • Performance. The callback runs about n log n times. Compute expensive keys once with array_map() and use array_multisort() when the data set is large.
  • Do not modify the array being sorted inside the callback.