wp_list_sort() and WP_List_Util in 4.7

If you have been working with arrays of multiple objects or arrays of multiple arrays before, you might be familiar with the functions wp_list_filter(), wp_list_pluck(), and wp_filter_object_list() which is essentially a combination of the previous two. WordPress 4.7 brings a few enhancements to handling such object or array lists.

New Utility Function to Sort Lists

WordPress 4.7 introduces a new function wp_list_sort() that makes it easy to sort object or array lists by one or more of its elements’ properties.

Usage

In addition to the function’s first parameter $list which should receive the array to sort, you can pass the name of one of the elements’ properties as the second parameter $orderby and the sort direction (either ‘ASC’ or ‘DESC’) as the third parameter $order. For example, if you had a list of post objects and you needed to sort them by their dates in descending order, you would use the function as follows:

$sorted_posts = wp_list_sort( $posts, 'post_date', 'DESC' )

Similar to the orderby and order arguments of the query classes in WordPress, the function also supports sorting by multiple properties by passing an array of properties and their sort direction as the $orderby parameter. When using the function like this, the $order parameter can be omitted and will be ignored. For example, here’s how you’d first order some posts by their dates in descending order and then by their titles in ascending order afterwards:

$sorted_posts = wp_list_sort( $posts, array(
  'post_date'  => 'DESC',
  'post_title' => 'ASC',
) )

The fourth parameter $preserve_keys is a boolean and can be set to true if the array is associative and its keys should be preserved. By default the parameter is set to false, thus most appropriate for indexed arrays.

Internals

Internally the function uses PHPPHP The web scripting language in which WordPress is primarily architected. WordPress requires PHP 5.6.20 or higher’s usort() by default, or uasort() if the $preserve_keys parameter is set to true. Numeric values will be compared by their amount while strings will be compared via strcmp(). The function should not be used to compare booleans or non-scalar values. Be aware that PHP’s sorting algorithms are not stable, so when two elements have identical values for all the properties compared, they will not necessarily remain in the same order as before.

Better Organization of List Utilities

While wp_list_sort() provides new functionality, existing list utilities have been revamped as well: WordPress 4.7 introduces a new WP_List_Util class as a central access point for handling lists. The previously mentioned functions have been adjusted to become wrappers for methods inside that new class.

Beside the structural improvements of moving such functionality into a centralized class, the class provides an optimized way to run multiple tasks on a list, e.g. filtering, sorting and plucking a property out of a list through one instance of the class.

By using the method WP_List_Util::get_output() you can access the list in its current state at any time, while WP_List_Util::get_input() can be used to access it in its original state. A good example on how to use the new class is wp_filter_object_list() which handles both filtering and plucking a property.

For the background discussion around these changes, see #37128.

#4-7, #dev-notes