PHP usort() Function

Beginner
5 min read
Updated: Nov 2026
3 examples
Array

Definition

In PHP, usort() sorts the values of an array using your own comparison function and gives them new keys 0, 1, 2 and so on.

Use usort() when the normal sort() does not fit, for example when you want to sort users by age, words by length, or products by price. You write a small function that says which of two values should come first.

Syntax

Call usort() with the values you need. Start with this line.

PHP
usort($numbers, fn($a, $b) => $b <=> $a);
CallWhat it does
usort($numbers, fn($a, $b) => $b <=> $a)Sorts the numbers from high to low.
usort($words, fn($a, $b) => strlen($a) <=> strlen($b))Sorts the words by their length.
usort($users, fn($a, $b) => $a["age"] <=> $b["age"])Sorts records by one field.

The callback receives two values and must return a negative number, zero or a positive number. usort() changes the original array and returns true. Since PHP 8.0 the sort is stable, so equal items keep their original order.

Library declarations
PHP
usort(array &$array, callable $callback): true

Parameters

ParameterDescription
arrayRequired. The array to sort. It is passed by reference and changed in place.
callbackRequired. A function that takes two values and returns an integer less than, equal to or greater than zero. This sets the order.

Return Value

Return ValueDescription
trueAlways returns true. The sorted result is stored in the array you passed in.

PHP Examples

Example 1 — Sort Numbers from High to Low

The callback compares two numbers. Writing $b <=> $a puts the larger one first.

PHP
<?php
$numbers = [5, 2, 8, 1];

usort($numbers, fn($a, $b) => $b <=> $a);

echo implode(", ", $numbers), PHP_EOL;

How It Works

  1. $numbers holds four numbers.
  2. PHP calls the arrow function with two numbers at a time.
  3. $b <=> $a gives a positive result when $b is larger, so larger numbers move to the front.
  4. implode() prints the sorted numbers.

Example 2 — Sort Words by Length

Words with the same length keep their original order, because the sort is stable in PHP 8.

PHP
<?php
$words = ["pear", "fig", "banana", "kiwi"];

usort($words, fn($a, $b) => strlen($a) <=> strlen($b));

echo implode(", ", $words), PHP_EOL;

How It Works

  1. The lengths are pear 4, fig 3, banana 6 and kiwi 4.
  2. strlen() gives the length of each word inside the callback.
  3. The shortest word, fig, goes first and banana goes last.
  4. pear and kiwi have the same length, so PHP 8 keeps pear before kiwi, the same as in the original array.

Example 3 — Sort Records by One Field

Each user is an array. The callback picks the age field to decide the order.

PHP
<?php
$users = [
    ["name" => "Tom", "age" => 30],
    ["name" => "Ann", "age" => 25],
    ["name" => "Raj", "age" => 35],
];

usort($users, fn($a, $b) => $a["age"] <=> $b["age"]);

foreach ($users as $user) {
    echo $user["name"], " (", $user["age"], ")", PHP_EOL;
}

How It Works

  1. $users holds three small arrays with a name and an age.
  2. The callback compares the "age" field of the two users it receives.
  3. usort() orders the users from the youngest to the oldest.
  4. The foreach loop prints each user in the new order.

Frequently Asked Questions

It sorts the values of an array with a comparison function that you write, and renumbers the keys from 0.
sort() uses PHP's built-in comparison rules. usort() lets you define your own, which is needed for records, custom orders and special rules.
usort() replaces the keys with 0, 1, 2. uasort() keeps the keys.
A negative number if the first value goes first, zero if they are equal, and a positive number if the second value goes first. The <=> operator does exactly this.
No. It changes the array you pass in and returns true.

Back to Array Functions

Browse all PHP array function tutorials.

Array functions →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

8 people found this page helpful