Searching for files

An API is provided by the file abstraction layer (FAL) to search for files in a storage or folder. It includes matches in meta data of those files. The given search term is looked for in all search fields defined in TCA of sys_file and sys_file_metadata tables.

Searching for files in a folder

EXT:my_extension/Classes/SearchInFolderExample.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Classes;

use TYPO3\CMS\Core\Resource\Folder;
use TYPO3\CMS\Core\Resource\InaccessibleFolder;
use TYPO3\CMS\Core\Resource\Search\FileSearchDemand;
use TYPO3\CMS\Core\Resource\StorageRepository;

final class SearchInFolderExample
{
    public function __construct(
        private readonly StorageRepository $storageRepository,
    ) {}

    public function search($searchWord): void
    {
        $folder = $this->getFolderFromDefaultStorage('/some/path/in/storage/');

        $searchDemand = FileSearchDemand::createForSearchTerm($searchWord)->withRecursive();
        $files = $folder->searchFiles($searchDemand);

        // ... more logic
    }

    private function getFolderFromDefaultStorage(string $path): Folder|InaccessibleFolder
    {
        $defaultStorage = $this->storageRepository->getDefaultStorage();

        return $defaultStorage->getFolder($path);
    }
}

Searching for files in a storage

EXT:my_extension/Classes/SearchInStorageExample.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Classes;

use TYPO3\CMS\Core\Resource\Search\FileSearchDemand;
use TYPO3\CMS\Core\Resource\StorageRepository;

final class SearchInStorageExample
{
    public function __construct(
        private readonly StorageRepository $storageRepository,
    ) {}

    public function search($searchWord): void
    {
        $storage = $this->storageRepository->getDefaultStorage();

        $searchDemand = FileSearchDemand::createForSearchTerm($searchWord)->withRecursive();
        $files = $storage->searchFiles($searchDemand);

        // ... more logic
    }
}

Add additional restrictions

It is possible to further limit the result set, by adding additional restrictions to the FileSearchDemand. Please note, that FileSearchDemand is an immutable value object, but allows chaining methods for ease of use:

EXT:my_extension/Classes/SearchInStorageWithRestrictionsExample.php

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Classes;

use TYPO3\CMS\Core\Resource\Search\FileSearchDemand;
use TYPO3\CMS\Core\Resource\StorageRepository;

final class SearchInStorageWithRestrictionsExample
{
    public function __construct(
        private readonly StorageRepository $storageRepository,
    ) {}

    public function search($searchWord): void
    {
        $storage = $this->storageRepository->getDefaultStorage();

        // Get the 10 biggest files in the storage
        $searchDemand = FileSearchDemand::createForSearchTerm($searchWord)
            ->withRecursive()
            ->withMaxResults(10)
            ->addOrdering('sys_file', 'size', 'DESC');
        $files = $storage->searchFiles($searchDemand);

        // ... more logic
    }
}

API

class FileSearchDemand

Fully qualified name: \TYPO3\CMS\Core\Resource\Search\FileSearchDemand

Immutable value object that represents a search demand for files.

create ( )

Returns: self

createForSearchTerm ( string $searchTerm)

param $searchTerm: the searchTerm

Returns: self

getSearchTerm ( )

Returns: ?string

getFolder ( )

Returns: ?\TYPO3\CMS\Core\Resource\Folder

getFirstResult ( )

Returns: ?int

getMaxResults ( )

Returns: ?int

getSearchFields ( )

Returns: ?array

getOrderings ( )

Returns: ?array

isRecursive ( )

Returns: bool

withSearchTerm ( string $searchTerm)

param $searchTerm: the searchTerm

Returns: self

withFolder ( \TYPO3\CMS\Core\Resource\Folder $folder)

param $folder: the folder

Returns: self

withStartResult ( int $firstResult)

Requests the position of the first result to retrieve (the "offset").

Same as in QueryBuilder it is the index of the result set, with 0 being the first result.

param $firstResult: the firstResult

Returns: self

withMaxResults ( int $maxResults)

param $maxResults: the maxResults

Returns: self

addSearchField ( string $tableName, string $field)

param $tableName: the tableName
param $field: the field

Returns: self

addOrdering ( string $tableName, string $fieldName, string $direction = 'ASC')

param $tableName: the tableName
param $fieldName: the fieldName
param $direction: the direction, default: 'ASC'

Returns: self

withRecursive ( )

Returns: self

Performance optimization in a custom driver

A driver capability \TYPO3\CMS\Core\Resource\ResourceStorageInterface::CAPABILITY_HIERARCHICAL_IDENTIFIERS is available to implement an optimized search with good performance. Drivers can optionally add this capability in case the identifiers constructed by the driver include the directory structure. Adding this capability to drivers can provide a big performance boost when it comes to recursive search (which is the default in the file list and file browser UI).