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.