usort

Sort an array by values using a user-defined comparison function

&reftitle.description; `true` `usort` `array` `array` `callable` `callback`

Sorts `array` in place by values using a user-supplied comparison function to determine the order.

¬e.sort-unstable; ¬e.no-key-association;
&reftitle.parameters;

`array`

- The input array.

`callback`

- &sort.callback.description;
&reftitle.returnvalues;

&return.true.always;

&reftitle.changelog;

&Version; | &Description;
&return.type.true; &array.changelog.by-ref;

&reftitle.examples;

### `usort` example

    <?php
    function cmp($a, $b)
    {
        if ($a == $b) {
            return 0;
        }
        return ($a < $b) ? -1 : 1;
    }

    $a = array(3, 2, 5, 6, 1);

    usort($a, "cmp");

    foreach ($a as $key => $value) {
        echo "$key: $value\n";
    }
    ?>

&example.outputs;

    0: 1
    1: 2
    2: 3
    3: 5
    4: 6

The spaceship operator may be used to simplify the internal comparison even further.

    <?php
    function cmp($a, $b)
    {
        return $a <=> $b;
    }

    $a = array(3, 2, 5, 6, 1);

    usort($a, "cmp");

    foreach ($a as $key => $value) {
        echo "$key: $value\n";
    }
    ?>

Obviously in this trivial case the `sort` function would be more appropriate.

### `usort` example using multi-dimensional array

    <?php
    function cmp($a, $b)
    {
        return strcmp($a["fruit"], $b["fruit"]);
    }

    $fruits[0]["fruit"] = "lemons";
    $fruits[1]["fruit"] = "apples";
    $fruits[2]["fruit"] = "grapes";

    usort($fruits, "cmp");

    foreach ($fruits as $key => $value) {
        echo "\$fruits[$key]: " . $value["fruit"] . "\n";
    }
    ?>

When sorting a multi-dimensional array, `$a` and `$b` contain references to the first index of the array.

&example.outputs;

    $fruits[0]: apples
    $fruits[1]: grapes
    $fruits[2]: lemons

### `usort` example using a member function of an object

    <?php
    class TestObj {
        private string $name;

        function __construct($name)
        {
            $this->name = $name;
        }

        /* This is the static comparing function: */
        static function cmp_obj($a, $b)
        {
            return strtolower($a->name) <=> strtolower($b->name);
        }
    }

    $a[] = new TestObj("c");
    $a[] = new TestObj("b");
    $a[] = new TestObj("d");

    usort($a, [TestObj::class, "cmp_obj"]);

    foreach ($a as $item) {
        echo $item->name . "\n";
    }
    ?>

&example.outputs;

    b
    c
    d

### `usort` example using a closure to sort a multi-dimensional array

    <?php
    $array[0] = array('key_a' => 'z', 'key_b' => 'c');
    $array[1] = array('key_a' => 'x', 'key_b' => 'b');
    $array[2] = array('key_a' => 'y', 'key_b' => 'a');

    function build_sorter($key) {
        return function ($a, $b) use ($key) {
            return strnatcmp($a[$key], $b[$key]);
        };
    }

    usort($array, build_sorter('key_b'));

    foreach ($array as $item) {
        echo $item['key_a'] . ', ' . $item['key_b'] . "\n";
    }
    ?>

&example.outputs;

    y, a
    x, b
    z, c

### `usort` example using the spaceship operator

The spaceship operator allows for straightforward comparison of compound values across multiple axes. The following example will sort `$people` by last name, then by first name if the last name matches.

    <?php
    $people[0] = ['first' => 'Adam', 'last' => 'West'];
    $people[1] = ['first' => 'Alec', 'last' => 'Baldwin'];
    $people[2] = ['first' => 'Adam', 'last' => 'Baldwin'];

    function sorter(array $a, array $b) {
        return [$a['last'], $a['first']] <=> [$b['last'], $b['first']];
    }

    usort($people, 'sorter');

    foreach ($people as $person) {
        print $person['last'] . ', ' . $person['first'] . PHP_EOL;
    }
    ?>

&example.outputs;

    Baldwin, Adam
    Baldwin, Alec
    West, Adam

&reftitle.seealso;

- `uasort`
- `uksort`
- &seealso.array.sorting;