---
title: "Searching for files"
manual: "TYPO3 Explained"
version: "11.5"
permalink: "https://docs.typo3.org/permalink/t3coreapi:fal-using-fal-examples-file-search@11.5"
source: "ApiOverview/Fal/UsingFal/ExamplesFileSearch.rst"
rendered: "2026-10-21T15:30:00+00:00"
---

> [!WARNING]
> **Attention**
>
> TYPO3 v11 has reached end-of-life as of October 31th 2024 and
> is no longer being maintained. Use the version switcher on the top
> left of this page to select documentation for a supported version of TYPO3.
>
> Need more time before upgrading?
> You can purchase Extended Long Term Support (ELTS) for TYPO3 v11 here:
> [TYPO3 ELTS](https://typo3.com/services/extended-support-elts).

# Searching for files {#fal-using-fal-examples-file-search}

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](https://docs.typo3.org/m/typo3/reference-tca/11.5/en-us/Ctrl/Properties/SearchFields.html#ctrl-reference-searchfields) of
`sys_file` and `sys_file_metadata` tables.

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

## Searching for files in a folder {#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\Search\FileSearchDemand;
use TYPO3\CMS\Core\Resource\StorageRepository;

final class SearchInFolderExample
{
    private StorageRepository $storageRepository;

    public function __construct(StorageRepository $storageRepository) {
        $this->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)
    {
        $defaultStorage = $this->storageRepository->getDefaultStorage();

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

```

## Searching for files in a storage {#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
{
    private StorageRepository $storageRepository;

    public function __construct(StorageRepository $storageRepository) {
        $this->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@11.5)

## Add additional restrictions {#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
{
    private StorageRepository $storageRepository;

    public function __construct(StorageRepository $storageRepository) {
        $this->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 {#api}

-   **class FileSearchDemand**

    -   *Fully qualified name:* `\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

There is also a driver capability
`\TYPO3\CMS\Core\Resource\ResourceStorageInterface::CAPABILITY_HIERARCHICAL_IDENTIFIERS`
to allow implementing an optimized search with good performance. Drivers can
optionally add this capability in case the identifiers that are 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
default in the file list and file browser UI).