TYPO3 File Abstraction Layer: Architecture Note on Requirements, Design, and Operational Checks

Requirements

TYPO3 needs a unified way to handle files regardless of where they are stored. The File Abstraction Layer must support multiple back-ends such as local filesystem, FTP and Amazon S3 through a common API.

Metadata including size, MIME type and custom properties is stored in the TYPO3 database while the file bytes remain in the storage. The layer must integrate with core features like page content elements and the backend file list, and respect backend user and group permissions and file mount definitions.

Smallest Suitable Design

The design centers on three concepts.

1. ResourceStorage drivers – PHP classes implementing TYPO3\CMS\Core\Resource\StorageInterface. Each driver knows how to read, write, list and delete files on its specific storage.
2. File and Folder objects – lightweight wrappers File and Folder that hold a reference to a storage, an identifier and cached properties.
3. Storage registry – configured in $GLOBALS['TYPO3_CONF_VARS']['SYS']['resources']. At bootstrap TYPO3 builds a StorageRepository that maps a storage name or uid to its driver instance.

All file operations in TYPO3 go through the FAL API, which delegates to the appropriate driver while keeping the caller storage-agnostic.

Example Storage Configuration

// LocalConfiguration.php
$GLOBALS['TYPO3_CONF_VARS']['SYS']['resources'] = [
  [
    'name' => 'local_fileadmin',
    'driver' => 'Local',
    'configuration' => [
      'basePath' => 'fileadmin/',
      'allowAllUploads' => true,
    ],
  ],
  [
    'name' => 's3_assets',
    'driver' => 'AmazonS3',
    'configuration' => [
      'bucket' => 'my-typo3-assets',
      'region' => 'eu-west-1',
      'key'    => '%%env:AWS_ACCESS_KEY_ID%%',
      'secret' => '%%env:AWS_SECRET_ACCESS_KEY%%',
    ],
  ],
];

After changing this array, clear the system cache with typo3cms cache:flush so TYPO3 rebuilds the storage repository.

Trust and Data Boundaries

Each storage defines its own trust boundary. Raw file bytes never leave the storage; they are read or written directly by the driver.

Metadata and the relationship between a file and its storage are persisted in TYPO3 tables sys_file and sys_file_metadata. Access control is enforced by checking the BE user permissions against the file mount and the storage driver capabilities.

Because metadata lives in the database, a storage can be swapped or temporarily unavailable without losing references as long as the file records remain intact.

Operational Checks

FAL includes built-in health checks that administrators should run regularly.

1. Driver self-test – Every driver must implement testUploadFolder and getPublicUrl. The install tool calls these to verify readability and writability.
2. Scheduled storage health task – The core scheduler ships a task Storage: Check storage availability that runs testUploadFolder for each storage and logs failures.
3. CLI synchronization – typo3cms resource:storage:update walks through every storage, compares the physical file list with sys_file and updates the index. Running this after a storage configuration change prevents dangling database references.

Verification can be done by inspecting File > Filelist in the backend and confirming storages match LocalConfiguration.php, and by running typo3cms resource:storage:update and checking the reported counts against the actual storage contents.

Failure Modes

• Driver misconfiguration – Wrong credentials or base path cause testUploadFolder to return false, leading to missing files in the backend and exceptions on upload.
• Storage unavailability – Network loss or service downtime makes reads and writes fail. FAL throws an exception and the frontend may show broken images unless a fallback storage is configured.
• Metadata corruption – Accidental truncation of sys_file or sys_file_metadata results in lost properties while physical files remain intact.
• Race conditions – FAL does not provide file-level locking. Concurrent uploads from multiple frontend nodes can overwrite files unless the underlying storage guarantees atomic operations.

Conditions That Would Change the Design

The current FAL assumes strong consistency for metadata and storage APIs that provide atomic upload semantics.

Adoption of cloud-native object storage with eventual consistency would require a stricter consistency layer or write-through cache to avoid stale reads.

Need for cross-node file locking in clustered environments would require a distributed lock manager or a storage with native locking.

Regulatory demands for immutable storage would require treating uploads as new versions and prohibiting overwrites, moving versioning logic closer to the storage layer.