Searching and Sorting Users with the UserList Object

Mar 4, 2016
By admin

Concrete CMS provides the Concrete\Core\User\UserList object to make it easy for developers to query Concrete for a list of users based on different criteria.

Any time you want to sort, search or filter a list of users you should use this object (rather than querying the database directly), as it provides a nice API on top of the fairly complex table structure underneath.

To fetch a list of all users in your site:

$list = new \Concrete\Core\User\UserList();
$users = $list->getResults();

This is an array of all UserInfo objects, with no limit.

Basic Filtering Examples

Filtering a UserList query involves calling a filterBy...() function prior to getResults().

To filter by keywords (simple):

$list->filterByKeywords('andrew');

Filtering by keywords performs a simple LIKE query against users' usernames or email addresses, as well as the textual representation of any user attributes that have been marked as "included in search index".

To perform a more advanced search on the name, description and text content fields using MySQL's FULLTEXT search indexing:

$list->filterByFulltextKeywords('foobar');

If you want to filter by usernames, you have two options

$list->filterByUsername('foobar');
$list->filterByFuzzyUsername('foobar');

The second option will search within substrings – while the first will only return exact matches.

Filter By Groups

A common use case for the UserList object is filtering by user groups. This is easy to do. The following gets all users who are in the Administrators group:

$list->filterByGroup('Administrators');

You can also pass a group object to the method:

$group = \Group::getByName('Administrators');
$list->filterByGroup($group);

You can also search for users specifically NOT in a group, by passing false as the second argument to the method:

$group = \Group::getByName('Administrators');
$list->filterByGroup($group, false); // Return all non-admins

Filter by Attribute

The UserList object contains some 'magic methods' to filter easily by attributes. Simply add a StudlyCapsed attribute handle after filterBy and pass the data into the attribute:

$list->filterByProfilePrivateMessagesEnabled(true);

The attribute's type determines what kind of data it takes in its filter methods.

Sorting

To sort the list by the date a user was added:

$list = new \Concrete\Core\User\UserList();
$list->sortByDateAdded();
$$users = $list->getResults();

To sort by the order shown in the sitemap:

$list->sortByUserName();

Pagination

Once you have filtered your UserList object, getResults() will return all matching users.

Many times, however, you'll want to retrieve just few results at a time. For this, you'll want to use the Pagination object:

$list = new \Concrete\Core\User\UserList();
$pagination = $list->getPagination();
$pagination->setMaxPerPage(10)->setCurrentPage(2);
$results = $pagination->getCurrentPageResults();

Pagination and Advanced Functions

Since the UserList is a subclass of the built-in database item lists, all the advanced techniques and pagination API described within the PageList documentation is available here.

API Reference

UserList API Reference

Pagination API Reference

Was this information useful?
Thank you for your feedback.