TYPO3 FAL Architecture Note: Storage, Metadata, and Trust Boundaries

Many TYPO3 projects fail after deployment because templates and extensions reference raw filesystem paths such as fileadmin/user_upload/. When the site moves to a different server, a shared volume, or an object store, those references break silently. The File Abstraction Layer (FAL) exists to prevent this by making the database the source of truth for file metadata while the physical location stays configurable. This note describes the smallest FAL design that holds up in production, where the trust boundaries lie, and what to check before and after a release.

Requirements FAL Is Meant to Satisfy

FAL centralises file storage across local directories, S3-compatible buckets, FTP servers, and other drivers. Every file is represented by a database record in sys_file that stores metadata such as size, MIME type, and timestamps. Content elements link to files through relation records in sys_file_reference, not through hard-coded paths. The backend Media Library and Filelist modules consume FAL services, so editors never touch the filesystem directly. Extensions perform create, read, update, and delete operations through the PHP API—classes such as \TYPO3\CMS\Core\Resource\Storage and \TYPO3\CMS\Core\Resource\File—which keeps behaviour consistent regardless of the underlying driver.

Smallest Suitable Design

For a standard single-server site, the smallest viable design uses one local storage. The storage record in sys_file_storage points to a directory that the web server user can write to, and all public URLs derive from that configuration. Files are never referenced by absolute path in Fluid templates or TypoScript; instead, extensions and templates resolve a FileReference object and ask it for the public URL. Processed derivatives—thumbnails, cropped images—live in a separate processing folder so that source files remain untouched. The database record is authoritative: if the physical file is missing, FAL reports a missing file rather than guessing a path.

Configuration Boundaries

Storage configuration lives in the database, not in YAML files. Each storage record defines the driver, the driver-specific configuration (for example, a local base path or S3 credentials), and the public URL prefix. Because the record is database-bound, moving a site between environments requires either exporting and importing the storage records or re-creating them so that the path matches the target filesystem. Sharing a single storage record across environments without a shared backend produces orphaned files and broken references.

Trust and Data Boundaries

Three trust boundaries matter. First, the web server process must have read and write access to the storage directory, but it should not have write access outside that directory. Second, backend users are granted read or write permissions per storage; FAL checks these rights before performing operations, so a user without write access cannot replace a file even if they know its identifier. Third, extensions must cross the API boundary: calling ResourceFactory::getInstance() or injecting the storage repository is supported, whereas using rename() or file_put_contents() on storage paths bypasses metadata tracking and locking. FAL also uses file locking to prevent concurrent edits from corrupting metadata, so custom code that manipulates files outside the API risks lost updates.

Operational Checks

Before declaring a FAL setup healthy, run these checks.

1. Backend inventory. Navigate to File > Filelist and confirm that the expected storage appears and that the file tree matches the intended directory.
2. API smoke test. In a TYPO3 CLI command (for example, registered via Configuration/Commands.php and invoked with vendor/bin/typo3 <command>), retrieve a storage and count its files. Replace <storage-uid> with the actual UID from sys_file_storage:

<?php
use TYPO3\CMS\Core\Resource\ResourceFactory;
use TYPO3\CMS\Core\Utility\GeneralUtility;

$resourceFactory = GeneralUtility::makeInstance(ResourceFactory::class);
$storage = $resourceFactory->getStorageByUid(<storage-uid>);
$files = $storage->getFileObjects();
echo count($files) . PHP_EOL;

Run the command as the same user that runs the web server. The expected result is a non-zero integer that matches the number of sys_file records for that storage, and no thrown exception. A zero count or an exception usually means the storage path is wrong or the database records are missing.

1. Upload round-trip. Upload a test file through the Media Library. Confirm that a row appears in sys_file with the correct size and MIME type, and that the physical file exists in the configured directory or bucket.
2. Metadata propagation. Edit the file's title or alternative text in the backend and reload a page that renders the file. The change should appear without clearing all caches manually, because FAL registers cache tags that invalidate dependent entries.
3. Permission failure. Temporarily remove write access from the storage directory and attempt an upload. The backend should display an error, and no new sys_file record should be created. Restore permissions immediately after the test.

Failure Modes and How They Surface

Failure mode	Symptom	Root cause to check
Silent upload failure	UI reports success, but file is absent	Storage path mismatch or web server lacks write permission
Large file rejection	Upload stops at a size limit	post_max_size, upload_max_filesize, or max_execution_time
Slow rendering with remote storage	Page latency spikes on file URLs	On-the-fly URL generation to S3/FTP; no CDN or pre-generated URLs
Stale content after file edit	Old image or title persists	Cache backend disabled or FAL cache tags not flushed
Concurrent metadata corruption	Random missing titles or identifiers	Custom code editing files outside the FAL locking mechanism

Overusing FAL hooks for heavy work—virus scanning, video transcoding—blocks the request thread. The hook fires synchronously, so a slow scanner turns an upload into a timeout. Move long-running tasks to a background worker or queue worker instead.

Conditions That Change the Design

The minimal single-storage design stops being sufficient under specific conditions.

Condition	Required design change
Multiple application servers	Configure one shared storage (NFS, S3, or similar) so every node sees the same files and metadata
Heavy file processing	Off-load transformations and scanning to background workers; keep FAL hooks for lightweight validation only
Remote storage with public traffic	Introduce a CDN or pre-generate public URLs to avoid per-request network calls
Custom security policy	Run virus scanning asynchronously and quarantine via a separate storage rather than blocking the upload hook

FAL is a supported core feature, but it is not a magic fix for every deployment shape. The database-backed metadata model works only when the storage configuration, filesystem permissions, and cache backend are aligned. Run the operational checks above after every environment change, and treat any mismatch between sys_file and the physical storage as a release blocker.