Searching and Sorting Users with the UserList Object

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