WP_List_Util, a WP native class to handle operations on arrays

Sometimes we rely on PHP’s native functions and methods to solve problems in WordPress. In some of those cases, we definitely ask ourselves why there are no WP functions or classes to keep things “home”.

Arrays can be managed in uncountable ways. However, sometimes we want just to use the WP core functions and keep things simple, but performing common operations like sorting, filtering or so.

Well, in fact WordPress has a small and simple class to help developers to manage list and arrays of objects: WP_List_Util. You probably heard, if you code in WP for some time, about WP_List_Table, which is basically used to create custom admin lists.

Just the array of argument

WP_List_Util admits a single argument: the array containing the data you want to handle and filter. Once the class is instatiated for the desired data, the developer can perform any combination of operations, and then return the class object – the resulting array.

Two methods allow us to retrieve the original array and the resulting array, after all operations done: get_input() and get_output(). Between these two states, we can perform three different sets of operations:

Sorting
Filtering
Plucking

To see how those operations can be used, briefly, let’s use a simple multidimensional array for illustrating the examples.

$marks = array( 
    "jack" => array (
        "physics" => 35,
        "maths" => 30,	
        "chemistry" => 39
    ),
    "william" => array (
        "physics" => 30,
        "maths" => 32,
        "chemistry" => 29
    ),
    "matt" => array (
        "physics" => 31,
        "maths" => 22,
        "chemistry" => 39
    ));

WP_List_Util – sorting data

Let’s start with sorting operations. First things first, we need to create a new instance of the class, passing our example array. Then, let’s call the method get_input(), just to check the initial state of the data.

$list = new WP_List_Util($marks);
print_r($list->get_input());

/* Results in

Array (
    [jack] => Array
        (
            [physics] => 35
            [maths] => 30
            [chemistry] => 39
        )
    [william] => Array
        (
            [physics] => 30
            [maths] => 32
            [chemistry] => 29
        )
    [matt] => Array
        (
            [physics] => 31
            [maths] => 22
            [chemistry] => 39
        ))
*/

Cool, now we use the WP_List_Util object to apply the sort() method, which admits three arguments: the field or fields to order by, whether the sorting will be ascendent or descendent and whether to keep the array keys or not.

$list = new WP_List_Util($marks);
$list->sort('physics', 'DESC', true);
print_r($list->get_output());

/*
Results in 

Array (
    [jack] => Array
        (
            [physics] => 35
            [maths] => 30
            [chemistry] => 39
        )
    [matt] => Array
        (
            [physics] => 31
            [maths] => 22
            [chemistry] => 39
        )
    [william] => Array
        (
            [physics] => 30
            [maths] => 32
            [chemistry] => 29
        ))
*/

The variable $list corresponds to the class instance for the array we defined. So, applying the method sort() for ordering by the field “physics“, and in a descendent logic, plus TRUE as a third argument, for keeping the array keys (names), we can get an output as provided above.

WP_List_Util – filtering data

The class also allows us to filter the array data, removing nodes we don’t want to deal with, for instance. For such, the following example just keeps nodes which match one of the conditions established.

$list = new WP_List_Util($marks);
$list->filter(['chemistry' => 39, 'physics' => 31], 'OR');
print_r($list->get_output());

/*
Results in

Array (
    [jack] => Array
        (
            [physics] => 35
            [maths] => 30
            [chemistry] => 39
        )
    [matt] => Array
        (
            [physics] => 31
            [maths] => 22
            [chemistry] => 39
        ))
*/

This will filter the array, just keeping those nodes in which the field “chemistry” brings the value 39 OR the field “physics” is equal to 31. The logic operator could be either AND or NOT, so the same conditions can be used for generating different outputs.

WP_List_Util – the pluck operator

Finally, this class also allows us to pluck elements of the array object. Some people still get confused about plucking, but it is actually quite simple. This operates does nothing more than segregating a single field from the array, creating a new array just with that field’s values. The example clarifies.

$list = new WP_List_Util($marks);
$list->pluck('chemistry');
print_r($list->get_output());

/*
Results in

Array (
    [0] => 39
    [1] => 29
    [2] => 39
)
*/

Before ending this article, remember that using native PHP functions is not a problem in WordPress. However, some may prefer to keep the coding “WP-only”, and in this case, this utility class is something to be widely used.

Just the array of argument

WP_List_Util – sorting data

WP_List_Util – filtering data

WP_List_Util – the pluck operator

Like this: