wp_list_sort() │ WP 4.7.0

Sorts an array of objects or an array of arrays by one or more fields.

Convenient to use for subsequent sorting of query results, for example, posts.

See also the PHP function array_multisort(). It may be better suited for non-standard array sorting options.

If the array being sorted does not have a field specified for sorting (or has a value of null), then that element of the array will remain in place (it will not float up or sink down).

For example: we are sorting by a numeric field in DESC order. In this case, we might expect that if the field is missing (or has a value of null, then its value will be considered 0), it will go down (sink). But in reality - this is not the case - the element without the sorting field will remain in place and will not move anywhere.

$animals = [
	'dog'    => (object) [ 'id' => 'dog',    'price' => 888 ],
	'cat'    => (object) [ 'id' => 'cat',     ],
	'falcon' => (object) [ 'id' => 'falcon', 'price' => 777 ],
	'bat'    => (object) [ 'id' => 'bat',    'price' => 0 ],
];

$res = wp_list_sort( $animals, [ 'price' => 'DESC' ], '', true );
/*
Array(
	[dog] => stdClass Object(
		[id] => dog
		[price] => 888
	)
	[cat] => stdClass Object(
		[id] => cat
	)
	[falcon] => stdClass Object(
		[id] => falcon
		[price] => 777
	)
	[bat] => stdClass Object(
		[id] => bat
		[price] => 0
	)
)
*/

Uses: WP_List_Util()

No Hooks.

Returns

Array. Sorted array.

Usage

wp_list_sort( $list, $orderby, $order, $preserve_keys );

$list(array) (required): Array of objects to be sorted.
$orderby(string/array): Name of the field by which to sort. An array of several names can be specified: array('field'=>'order', 'post_name'=>'ASC')
Default: array()
$order(string): Sorting order. Can be: 'ASC' or 'DESC'. Used only if a string is specified in the previous parameter.
Default: 'ASC'
$preserve_keys(boolean): Whether to preserve the array keys when sorting. true - preserve or false - do not preserve.
Default: false

Examples

#1 An example of sorting a multidimensional array

$animals = [
	'alligator' => [ 'name' => 'alligator', 'class' => 'reptile' ],
	'dog'       => [ 'name' => 'dog',       'class' => 'mammal' ],
	'cat'       => [ 'name' => 'cat',       'class' => 'mammal' ],
	'falcon'    => [ 'name' => 'falcon',    'class' => 'bird' ],
	'bat'       => [ 'name' => 'bat',       'class' => 'mammal' ],
];

$res = wp_list_sort( $animals, 'class' );

print_r( $res );
/*
[
	0 => [ name => falcon,    class => bird ]
	1 => [ name => cat,       class => mammal ]
	2 => [ name => dog,       class => mammal ]
	3 => [ name => bat,       class => mammal ]
	4 => [ name => alligator, class => reptile ]
]
*/

$res = wp_list_sort( $animals, 'name', 'DESC' );

print_r( $res );
/*
[
	0 => [ name => falcon,    class => bird    ]
	1 => [ name => dog,       class => mammal  ]
	2 => [ name => cat,       class => mammal  ]
	3 => [ name => bat,       class => mammal  ]
	4 => [ name => alligator, class => reptile ]
]
*/

$res = wp_list_sort( $animals, 'name', 'ASC', true );

print_r( $res );
/*
[
	alligator => [ name => alligator, class => reptile ]
	bat       => [ name => bat,       class => mammal  ]
	cat       => [ name => cat,       class => mammal  ]
	dog       => [ name => dog,       class => mammal  ]
	falcon    => [ name => falcon,    class => bird    ]
]
*/

#2 An example of sorting an array of objects (posts)

Suppose we got the posts from the database. Then we did something with them. For example, we checked them and deleted some of them. Now we need to sort them.

// get an array of objects, here they are posts...
$posts = get_posts( [ 'posts_per_page'=>15 ] );

// do something with them

// sort by title from A to Z
$posts = wp_list_sort( $posts, 'post_title', 'ASC' );

//or like this
$posts = wp_list_sort( $posts, [ 'post_title'=>'ASC' ] );

#3 Sorting by multiple fields

The function also allows you to sort an array of arrays or objects by several fields at once:

$array = [
	'a' => [ 'type'=>'Sedan',     'color'=>'Silver' ],
	'c' => [ 'type'=>'Universal', 'color'=>'Black' ],
	'b' => ['type'=>'Jura', 'color'=>'White' ],
	'd' => ['type'=>'Jura', 'color'=>'Purple' ],
];

$array = wp_list_sort( $array, [ 'type'=>'DESC', 'color'=>'ASC' ] );

print_r( $array );

/*
Array (
	[0] => Array (
			[type] => Social
			[color] => Purple
		)

	[1] => Array (
			[type] => Social
			[color] => White
		)

	[2] => Array (
			[type] => Universal
			[color] => Black
		)

	[3] => Array (
			[type] => Sedan
			[color] => Silver
		)
)
*/

See also sorting by multiple fields via custom usort() function.

#4 Multi-field sorting with array indexes

By default, the array indexes are not saved, but this can be corrected by passing the 4th parameter. This raises the question how to be, if we specify an array in the second parameter, what to specify in the 3rd parameter?

If the second parameter specifies an array, then the third parameter is simply ignored and we can specify anything there to then specify the fourth parameter:

$array = [
	'a' => [ 'type'=>'Sedan',     'color'=>'Silver' ],
	'c' => [ 'type'=>'Universal', 'color'=>'Black' ],
	'b' => ['type'=>'Jura', 'color'=>'White' ],
	'd' => ['type'=>'Jura', 'color'=>'Purple' ],
];

$array = wp_list_sort( $array, [ 'type'=>'DESC', 'color'=>'ASC' ], '', true );

print_r( $array );

/*
Array
	[d] => Array
			[type] => Social
			[color] => Purple

	[b] => Array
			[type] => Social
			[color] => White

	[c] => Array
			[type] => Universal
			[color] => Black

	[a] => Array
			[type] => Sedan
			[color] => Silver
)
*/

Changelog

Since 4.7.0

Introduced.

`wp_list_sort() wp list sort` code ^{WP 6.9}

wp-includes/functions.php

function wp_list_sort( $input_list, $orderby = array(), $order = 'ASC', $preserve_keys = false ) {
	if ( ! is_array( $input_list ) ) {
		return array();
	}

	$util = new WP_List_Util( $input_list );

	return $util->sort( $orderby, $order, $preserve_keys );
}