Concrete CMS provides the Concrete\Core\File\FileList object to make it easy for developers to query Concrete for a list of files based on different criteria. Any time you want to sort, search or otherwise filter a list of files you should use this object, as it checks permissions and provides a nice API to what is a fairly complex table structure underneath.
$list = new \Concrete\Core\File\FileList();
By default, this list will include every file in your site, since it's not filtered in any way. It will only include files that the current user can see, based on permissions.
$files = $list->getResults();
This is an array of all the files in the file manager, with no limit. Each entry is just a \Concrete\Core\File\File object.
Basic Filtering Examples
Filter by File Type. File Type is a class constant on the \Concrete\Core\File\Type\Type class. Available constants include:
- \Concrete\Core\File\Type\Type::T_IMAGE = 1
- \Concrete\Core\File\Type\Type::T_TEXT = 1
- \Concrete\Core\File\Type\Type::T_AUDIO = 1
- \Concrete\Core\File\Type\Type::T_DOCUMENT = 1
- \Concrete\Core\File\Type\Type::T_APPLICATION = 1
- \Concrete\Core\File\Type\Type::T_UNKNOWN = 1
$list->filterByType(\Concrete\Core\File\Type\Type::T_IMAGE);
Filter by Extension
$list->filterByExtension('png');
Filter By Keywords
$list->filterByKeywords('foobar');
Filtering by keywords is a simple like search against the filename, description, title, tags, username of uploader, as well as the textual representation of any file attributes that have been marked as "included in search index."
Filter By File Set
$set = \Concrete\Core\File\Set\Set::getByName('My File Set');
$list->filterBySet($set);
Include Files in No Sets
$list->filterByNoSet();
Filter By a Particular File Size (in KB)
$list->filterBySize(1024, 2048); // Only includes files that are between 1MB and 2MB in Size
Filter by Attribute
Filtering By Attribute is Easier
$list->filterByAttribute('width', 200, '>='); // Only include files where "width" is 200 or greater.
Sorting
Sort by filename is ascending alphabetical order.
$list->sortByFilenameAscending();
Sort by File Set Display Order. (Note: in order to use this method, you must include a single file set in your filter methods.)
$list->sortByFileSetDisplayOrder();
Permissions
By default, permissions will be checked for every file retrieved in the result set. Ignoring permissions for the logged-in user is easy:
$list->ignorePermissions();
Custom Queries
The FileList class has been completely rewritten in Concrete version 7 as reliant on the Doctrine DBAL QueryBuilder. You can grab the underlying QueryBuilder object in order to operate on it directly from any FileList object:
$query = $list->getQueryObject();
Subclassing
It's easy to subclass the FileList object. Check out the PageList documentation for subclassing information – the principles are the same
Pagination
Once you have filtered your FileList object, you can use getResults() to get the list of File objects. Many times, however, you'll want to retrieve just few results at a time. For this, you'll want to use the Pagination object.
$pagination = $list->getPagination();
With Permissions
If your File list is honoring permissions, the $pagination object will be an instance of the Concrete\Core\Search\Pagination\PermissionablePagination object. This means that the entire result set (up to 1000) will be loaded and then segmented, with the permissions checker run against it.
Without Permissions
If your FileList object is ignoring permissions, it simply returns a basic Concrete\Core\Search\Pagination\Pagination object, which is simpler.
Once you have a Pagination object it's a simple matter to operate on it. You can get the total number of results
print $pagination->getTotalResults();
You can get the total number of pages:
print $pagination->getTotalPages();
You can determine whether paging is necessary
$pagination->hasNexPage();
$pagination->hasPreviousPage();
And you can get the current page's results:
$pagination->setMaxPerPage(10)->setCurrentPage(2);
$results = $pagination->getCurrentPageResults();
Rendering Pagination
Common pagination output HTML is supported, including Bootstrap 2, Bootstrap 3, Basic Pagination, and Concrete's default styling (which is heavily Bootstrap 3 inspired.)
print $pagination->renderDefaultView(); // Outputs HTML for Bootstrap 3, useful in the Dashboard, etc…
You can also render any pagination view supported by Pagerfanta from your Pagination object. More information available here.
API Reference
There are additional filtering options and relevant methods available in the FileList class. These are detailed in the API documentation: