Searching and Sorting Users with the UserList Object
Concrete5 provides the
Concrete\Core\User\UserList object to make it easy for developers to query concrete5 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
UserList query involves calling a
filterBy...() function prior to
To filter by keywords (simple):
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:
If you want to filter by usernames, you have two options
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:
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
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:
The attribute's type determines what kind of data it takes in its filter methods.
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:
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.