---
title: "Searching for files"
manual: "TYPO3 Explained"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3coreapi:fal-using-fal-examples-file-search@main"
source: "ApiOverview/Fal/UsingFal/ExamplesFileSearch.rst"
modified: "2026-09-16T13:05:25+00:00"
---

# 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 supported TCA fields of the tables
`sys_file` and `sys_file_metadata`.

-   [Searching for files in a folder](https://docs.typo3.org/permalink/t3coreapi:searching-for-files-in-a-folder@main)
-   [Searching for files in a storage](https://docs.typo3.org/permalink/t3coreapi:searching-for-files-in-a-storage@main)
-   [Add additional restrictions](https://docs.typo3.org/permalink/t3coreapi:add-additional-restrictions@main)
-   [API](https://docs.typo3.org/permalink/t3coreapi:api@main)
-   [Performance optimization in a custom driver](https://docs.typo3.org/permalink/t3coreapi:performance-optimization-in-a-custom-driver@main)

## Searching for files in a folder

**EXT:my_extension/Classes/SearchInFolderExample.php**

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

```

> [!NOTE]
> **See also**
>
> [The StorageRepository class](https://docs.typo3.org/permalink/t3coreapi:fal-using-fal-examples-storage-repository@main)

## 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
<?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:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

    -   **createForSearchTerm(string $searchTerm)**

        -   *param $searchTerm:* the searchTerm

        *Returns:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

    -   **getSearchTerm()**

        *Returns:* `?string`

    -   **hasSearchTerm()**

        *Returns:* `bool`

    -   **getFolder()**

        *Returns:* `?TYPO3CMSCoreResourceFolder`

    -   **getFirstResult()**

        *Returns:* `?int`

    -   **getMaxResults()**

        *Returns:* `?int`

    -   **getSearchFields()**

        *Returns:* `?array`

    -   **getOrderings()**

        *Returns:* `?array`

    -   **isRecursive()**

        *Returns:* `bool`

    -   **withSearchTerm(string $searchTerm)**

        -   *param $searchTerm:* the searchTerm

        *Returns:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

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

        -   *param $folder:* the folder

        *Returns:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

    -   **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:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

    -   **withMaxResults(int $maxResults)**

        -   *param $maxResults:* the maxResults

        *Returns:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

    -   **addSearchField(string $tableName, string $field)**

        -   *param $tableName:* the tableName
        -   *param $field:* the field

        *Returns:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

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

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

        *Returns:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

    -   **withRecursive()**

        *Returns:* `TYPO3CMSCoreResourceSearchFileSearchDemand`

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