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
    }
}

See also

The StorageRepository class

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 TYPO3\CMS\Core\Resource\Search\FileSearchDemand

Immutable value object that represents a search demand for files.

create()

Return type

self

createForSearchTerm(string $searchTerm)

Parameters

• $searchTerm (string) -- the searchTerm

Return type

self

getSearchTerm()

Return type

string

getFolder()

Return type

TYPO3\CMS\Core\Resource\Folder

getFirstResult()

Return type

int

getMaxResults()

Return type

int

getSearchFields()

Return type

array

getOrderings()

Return type

array

isRecursive()

Return type

bool

withSearchTerm(string $searchTerm)

Parameters

• $searchTerm (string) -- the searchTerm

Return type

self

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

Parameters

• $folder (TYPO3\CMS\Core\Resource\Folder) -- the folder

Return type

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.

Parameters

• $firstResult (int) -- the firstResult

Return type

self

withMaxResults(int $maxResults)

Parameters

• $maxResults (int) -- the maxResults

Return type

self

addSearchField(string $tableName, string $field)

Parameters

• $tableName (string) -- the tableName

• $field (string) -- the field

Return type

self

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

Parameters

• $tableName (string) -- the tableName

• $fieldName (string) -- the fieldName

• $direction (string) -- the direction, default: 'ASC'

Return type

self

withRecursive()

Return type

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).