uasort()

Sorting Arrays in PHP with uasort()

The PHP uasort() function sorts an associative array by its values using a comparison function you write yourself, while keeping each value attached to its original key. The "u" stands for user-defined (you supply the comparison logic) and the "a" stands for associative (key/value pairs are preserved).

This page covers what uasort() does, its syntax, how to write a correct comparison function, and worked examples for plain, associative, and multidimensional arrays — every result shown is the real output of running the code.

What uasort() does and when to use it

Most of PHP's sort functions either ignore keys or only let you sort by the built-in comparison rules. uasort() gives you both things at once:

• You control the order. You pass a callback that decides which of any two values comes first, so you can sort by length, by a nested field, in reverse, by a custom priority list — anything you can express in code.
• Keys stay with their values. After sorting, $array["John"] still points to John's value; only the order in which the pairs are iterated changes.

Reach for uasort() when both of these are true: you need a custom rule and the keys are meaningful (a name, an ID, a slug). If the keys are just throwaway 0, 1, 2… positions, usort() is simpler because it reindexes for you. If you want to sort by the keys rather than the values, use uksort(). If you only need a plain ascending/descending value sort with no custom rule, asort() and arsort() do that without a callback.

Syntax

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

• array &$array — the array to sort. The & means it is passed by reference: uasort() sorts the array in place and returns true/false, it does not return a new sorted array.
• callable $callback — your comparison function. It receives two values, $a and $b, and must return an integer telling PHP their relative order.
• Return value — bool, always true (it returns a value so it can be used in expressions, but you normally call it for its side effect on $array).

Because the array is modified in place, write uasort($array, ...); on its own line — do not write $array = uasort($array, ...), which would overwrite your data with true.

Writing the comparison function

The callback compares two values and returns an integer:

• a negative number if $a should come before $b,
• 0 if their order does not matter (they are considered equal),
• a positive number if $a should come after $b.

The cleanest way to produce that is the spaceship operator <=>, which returns exactly -1, 0, or 1:

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

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

The older ($a < $b) ? -1 : 1 style works too, but it never returns 0, so equal elements get an arbitrary order. Prefer <=>; it is shorter, correct for the equal case, and works for numbers, strings, and arrays.

Example 1: Sorting values of an indexed array (keys preserved)

Here uasort() sorts the numbers ascending, but notice the original keys travel with the values — that is the difference from sort(), which would renumber them 0…9.

Output:

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

Example 2: Sorting an associative array by value

This is the most common use: sort people by age while keeping their names as keys.

Output:

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

To sort from oldest to youngest, flip the operands: fn($a, $b) => $b <=> $a.

Example 3: Sorting a multidimensional array by a nested field

When each element is itself an array, the callback receives the whole sub-array, so you index into it to pick the field to sort on. Here we sort by age ([1]).

Output:

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
        )

)

For rows keyed by an associative field, swap $a[1] for something like $a['age'].

uasort() vs usort()

The functions are identical except for the keys. Run the same data through both:

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

Output:

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

Common gotchas

• It returns true, not the array. Read the sorted result from the variable you passed in, not from the return value.
• The sort is not stable before PHP 8.0. If two values are equal, their relative order was implementation-defined in older versions. Since PHP 8.0, all sort functions (including uasort()) are stable, so equal elements keep their original order.
• Always handle the equal case. Returning 1 for "not less than" (instead of 0) can scramble equal elements on old PHP and is just incorrect; <=> handles it for free.

Related functions

• usort() — same custom-rule sort, but reindexes keys.
• uksort() — sort by keys with a custom callback.
• asort() / arsort() — value sort, ascending/descending, no callback needed.
• ksort() — sort by keys without a callback.
• Sorting arrays in PHP — overview of every sort function and when to use each.

Conclusion

uasort() is the tool for sorting an associative array by value with your own comparison rule while keeping keys intact. Pair it with the spaceship operator for clean, correct callbacks, remember that it sorts in place, and choose it over usort() whenever the keys carry meaning.

Practice