Working with Multiple User Metadata Queries

🎬 Introduction

When starting this series, we stated the point was:

The purpose of this article is going to cover how to retrieve records in a custom way by using built-in WordPress API functions that don’t require writing custom SQL.

And we laid out that we’re going to be:

• looking at how to modify the query for the All Users page
• and we’re going to be doing this by looking at two pieces of metadata

So let’s get started by working with a single metadata query.

💾 Working with Multiple Metadata Queries

Assume that we have some piece of custom user metadata that’s set by a third-party element. Maybe it’s another application, a plugin, or something that manipulates the user when sending information over the wire via the REST API.

Regardless, we know that we want to use this information to help customize how users are rendered on the All Users page in WordPress.

1️⃣ Using One Piece of Metadata

In this example, let’s say that the user has metadata associated with the account and its identified by a meta_key called Status and the meta_value can either be 1 or 2.

Further, let’s say that we want to order the user by their status and we want to order them in descending order (that is, we want those with the value of 2 to appear first).

First, we’ll set up the meta query so it looks like this:

$metaQuery = [
    'user_status' => [
        'key' => 'status'
    ]
];
Code language: PHP (php)

Then we’ll set the meta query on the incoming query that’s passed to the pre_get_users hook:

$metaQuery = [
    'user_status' => [
        'key' => 'status'
    ]
];
$query->set('meta_query', $metaQuery);
Code language: PHP (php)

And finally we’ll make sure that we order the by user_status and tell WordPress to order it in descending order.

$metaQuery = [
    'user_status' => [
        'key' => 'status'
    ]
];
$query->set('meta_query', $metaQuery);
$query->set('orderby', 'status');
$query->set('order', 'desc');
Code language: PHP (php)

The full code should look like this:

add_action(
    'pre_get_users',
    function ($query) {
        if (!isOnUsersPage()) {
            return $query;
        }

        $metaQuery = [
            'user_status' => [
                'key' => 'status'
            ]
        ];
        $query->set('meta_query', $metaQuery);
        $query->set('orderby', 'user_status');
        $query->set('order', 'desc');

        return $query;
    }
);
Code language: PHP (php)

This reads: If we’re not on the All Users page, then leave; otherwise, list all users by their status in descending order.

💡But Wait!

The problem with this code is that it’s hard to test if you don’t have any custom metadata with which to work. Luckily, WordPress stores some of its own user metadata so we can use something we have out of the box.

For example, let’s say we want to order the users in descending order by their nickname metadata. To test this, we can replace the above code with the following:

add_action(
    'pre_get_users',
    function ($query) {
        if (!isOnUsersPage()) {
            return $query;
        }

        $metaQuery = [
            'user_nickname' => [
                'key' => 'nickname'
            ]
        ];
        $query->set('meta_query', $metaQuery);
        $query->set('orderby', 'user_nickname');
        $query->set('order', 'desc');

        return $query;
    }
);
Code language: PHP (php)

If you run this code within your plugin, your All Users page should, by default, list all users in the database in reverse alphabetical order based on the nickname set in their profile.

But what happens if we want to utilize more than one piece of metadata? We’ll see how to do that in the final part of the series.