array_multisort()

Purpose

array_multisort() sorts several arrays in one operation, or sorts a multi-dimensional array by one or more of its dimensions. The first array is the primary sort key. When two of its elements compare as equal, the second array breaks the tie, then the third, and so on. The comparison is lexicographic. Elements in the later arrays are moved so they stay aligned with the elements of the first array.

The function sorts its arguments in place, because they are passed by reference. It is the usual tool for ordering a table of rows by several columns when you have extracted those columns into separate arrays.

Signature

In PHP 8.4 the declared return type is bool. The manual notes that only PHP 8.5 narrows it to true.

Parameters and defaults

• $array1: the first array to sort. It must be a variable, since it is taken by reference.
• $array1_sort_order: SORT_ASC (default) or SORT_DESC.
• $array1_sort_flags: how values are compared. The default is SORT_REGULAR. Other flags are SORT_NUMERIC, SORT_STRING, SORT_LOCALE_STRING and SORT_NATURAL. SORT_FLAG_CASE can be combined with SORT_STRING or SORT_NATURAL using bitwise OR for case-insensitive comparison.
• ...$rest: more arrays, each optionally followed by its own order and flags.

The order and flags arguments may appear in either order, and each may be left out. Both apply only to the array right before them.

Return value and failure cases

The function always returns true, so there is no need to check the result. Mistakes show up as exceptions, not as a false return. The most common one is arrays of different sizes, which raises a ValueError in PHP 8.

Example 1: sorting parallel arrays

The second array follows the first. Where the first array has a tie (100 and 100), the second array decides the order.

<?php
$ar1 = [10, 100, 100, 0];
$ar2 = [1, 3, 2, 4];
array_multisort($ar1, $ar2);
echo json_encode([$ar1, $ar2]), PHP_EOL;

[[0,10,100,100],[4,1,2,3]]

The tied 100 entries are ordered by their partners 3 and 2, so 2 comes before 3... but the second array is only compared after the first array's values tie. Here the second array ends up as 4, 1, 2, 3.

Example 2: sorting rows by columns

array_multisort() wants columns, not rows. Use array_column() to build one array per sort key. Pass the original rows array last, so it is reordered using the same permutation.

<?php
$data = [
    ['volume' => 67, 'edition' => 2],
    ['volume' => 86, 'edition' => 1],
    ['volume' => 85, 'edition' => 6],
    ['volume' => 98, 'edition' => 2],
    ['volume' => 86, 'edition' => 6],
    ['volume' => 67, 'edition' => 7],
];
$volume = array_column($data, 'volume');
$edition = array_column($data, 'edition');
array_multisort($volume, SORT_DESC, $edition, SORT_ASC, $data);
echo json_encode($data), PHP_EOL;

[{"volume":98,"edition":2},{"volume":86,"edition":1},{"volume":86,"edition":6},{"volume":85,"edition":6},{"volume":67,"edition":2},{"volume":67,"edition":7}]

The rows are ordered by volume descending, and rows with the same volume are ordered by edition ascending.

Example 3: case-insensitive sorting

Plain string comparison is case sensitive, so capital letters sort before lowercase ones. To sort ignoring case, sort a lowercase copy and let the real values ride along as the second array.

<?php
$array = ['Alpha', 'atomic', 'Beta', 'bank'];
$lower = array_map('strtolower', $array);
array_multisort($lower, SORT_ASC, SORT_STRING, $array);
echo json_encode($array), PHP_EOL;

["Alpha","atomic","bank","Beta"]

Edge cases

• Keys: string keys are preserved, but numeric keys are re-indexed starting at zero. The original numeric keys cannot be recovered.
• Stability: members that compare as equal keep their original relative order. Before PHP 8.0 that order was undefined.
• Internal pointer: the internal pointer of the array is reset to its first element.
• Size mismatch: every array passed must have the same number of elements, or a ValueError is thrown.
• Per-array options: the order and flags belong to the array immediately before them. They do not carry over to later arrays.

Common mistakes

1. Passing rows instead of columns. Calling the function directly on an array of rows does not sort by a field. Extract columns first.
2. Forgetting the rows array at the end. Sorting only $volume and $edition leaves $data unchanged. Add $data as the last argument.
3. Passing an expression. Because arguments are by reference, you must pass variables, not function results such as array_column(...) inline.
4. Expecting a sorted return value. The function returns a boolean. The sorted data is in the arrays you passed.
5. Expecting case-insensitive results by default. SORT_STRING and SORT_REGULAR are case sensitive. Use a lowercase helper column or combine SORT_STRING | SORT_FLAG_CASE.
6. Assuming one flag applies to all arrays. Give each array its own order and flags when they differ.

Related functions

• usort(): sorts by a custom comparison callback, which is often clearer for a single complex rule.
• array_column(): extracts the columns you need to feed into array_multisort().
• array_map(): builds normalized helper columns, such as lowercase copies.
• sort(), rsort() and natsort(): sort a single array.

Recap

Use array_multisort() when several arrays must be sorted in step or when you need to order rows by multiple columns. Provide columns as variables, set order and flags per array, add the full data array last if you want it reordered too, and remember that numeric keys are re-indexed. The return value is always true.