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);
    }
}
Copied!

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

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

API

class \TYPO3\CMS\Core\Resource\Search\ FileSearchDemand

Immutable value object that represents a search demand for files.

create ( )
returntype

self

createForSearchTerm ( string $searchTerm)
param string $searchTerm

the searchTerm

returntype

self

getSearchTerm ( )
returntype

string

getFolder ( )
returntype

TYPO3\CMS\Core\Resource\Folder

getFirstResult ( )
returntype

int

getMaxResults ( )
returntype

int

getSearchFields ( )
returntype

array

getOrderings ( )
returntype

array

isRecursive ( )
returntype

bool

withSearchTerm ( string $searchTerm)
param string $searchTerm

the searchTerm

returntype

self

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

the folder

returntype

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 int $firstResult

the firstResult

returntype

self

withMaxResults ( int $maxResults)
param int $maxResults

the maxResults

returntype

self

addSearchField ( string $tableName, string $field)
param string $tableName

the tableName

param string $field

the field

returntype

self

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

the tableName

param string $fieldName

the fieldName

param string $direction

the direction, default: 'ASC'

returntype

self

withRecursive ( )
returntype

self

Performance optimization in a custom driver

A driver capability \TYPO3\CMS\Core\Resource\Capabilities::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).

Changed in version 13.0

The CAPABILITY_* constants from the class \TYPO3\CMS\Core\Resource\ResourceStorageInterface were removed and are now available via the class \TYPO3\CMS\Core\Resource\Capabilities.