How To Make WP_User_Query Sort by Role

WordPress has a highly configurable role and capability mechanism which can allow for a great level of detail for user permissions. However, this can complicate seemingly simple tasks such as sorting or grouping a list of users by their role. It makes sense for WordPress to not provide this sorting functionality, even if it makes our job as developers slightly more difficult. Because of the complexity of the role and capability system, any sorting we do will be highly individualized. For this reason, WP_User_Query does not implement an orderby role option. But we can make WP_User_Query sort by role.¹

With built in PHP sorting methods, we can create comparison routines to fit our specific needs. I’m going to sort a list of users with with a simple set of requirements, and leave the more complicated examples as an exercise for the reader. A recent project I worked on required a front end page to search the user base, and return the matched users sorted by a specific role order. In this example, let’s choose a role order which is simply alphabetical.

Some of the underlying assumptions in this example are:

• Each user has an explicitly assigned role
• Each user has exactly one role
• Additionally granted capabilities do not override the role status

With all of that on the table, let’s take a look at what we’re doing.

<?php
 
// our custom sort just looks at role names alphabetically
function my_user_compare( $user_a, $user_b ) {
  $cmp = strcmp( $user_a->roles[ 0 ], $user_b->roles[ 0 ] );
  if ( 0 == $cmp ) { // the roles match
    return strcmp( $user_a->display_name, $user_b->display_name ); // so use display name
  }
  return $cmp;
}
 
$args = array(
  'search' => 'gmail.com',
  'search_columns' => array( 'user_email' )
);
 
$query = new WP_User_Query( $args );
 
$users = $query->get_results();
 
uasort( $users, 'my_user_compare' );

The goal of this example is to search the user base for gmail.com addresses and return a list sorted by role. The WP_User_Query setup is straightforward; we’re just passing some basic arguments to the object. Then we’ll store the results, which are returned in array form, in a variable we’ll use for sorting.

Our sorting is handled by a custom comparison method, my_user_compare, and invoked by a uasort call. It’s worthwhile reading the documentation on PHP array sorting, but the jist is the sort method handles the bulk of the sorting load while we only need to specify a way of comparing two given objects from the array.

Our compare method relies on the assumption that the two objects being compared are WP_User objects. The rules of this type of compare is the method must return integers less than, greater than, or equal to zero if the first argument is considered respectively less than, greater than, or equal to the second argument. From there we’re simply using strcmp, which follows the same rules as our custom compare method, to compare the users’ role names. If necessary when the roles match, we’ll compare their display names. This gives us a nice, ordered array of users that we can display on a page.

This example was simple, but even with a complicated role and capability scheme, you can have WP_User_Query sort by role.

¹ Yes, I understand WP_User_Query isn’t actually doing the sorting, but a “Custom Array Sorting with PHP” article just isn’t sexy.