filefill for TYPO3

filefill saves developers and agencies days of synchronisation effort, loading missing files from fileadmin on demand from the production server

Anyone working on an existing TYPO3 project knows the ritual: the local setup is in place, the database dump has been imported, but on every other page placeholders appear instead of images. The reason is trivial: the fileadmin directory of the live system contains gigabytes of assets that are missing locally. The classic solution used to be rsync or scp over hours. filefill cuts this step out entirely. Instead of copying all files upfront, the extension loads exactly the required file from the configured remote server on first access, on demand, transparently, with caching. For agencies that work on several projects at the same time, this saves not only storage but also hours per setup.

The productivity gain is larger than it looks at first glance. A new developer is not productive only after an hour of download waiting, but after a few minutes. A code review on a forgotten feature branch does not need a fresh file sync. A short reproduction of a bug report does not drag on for half a day. The small extension therefore addresses a real bottleneck in everyday developer work.

Typical use cases

The most common case is the local development setup. A developer clones the TYPO3 project, sets up DDEV or Docker and imports the current database dump. Instead of downloading an additional 30 GB of fileadmin data, they configure filefill with the base URL of the live system. On every page view that requests an image or document, the extension checks whether the file exists locally and loads it if needed. After a few days of work, only the files actually needed are local, the rest stays on the server.

The second case are staging environments. An agency maintains a staging system for every project where editors test content before go-live. These staging systems do not have to hold all images, only those of the current release. filefill ensures that older content still works because files are pulled from the live system on demand.

Third use: disaster recovery and hotfix scenarios. When a TYPO3 system has to be brought up quickly on a new machine, for example after a server failure or during an urgent environment migration, filefill can bridge asset procurement during the first hours until the full backup restore has finished.

Technical architecture

filefill hooks into the FAL system of TYPO3, more precisely into the resource retrieval mechanism. As soon as TYPO3 requests a file from the local storage and finds that it does not exist, an event listener from filefill steps in. The extension checks a list of configured “sources” in their priority order and tries to load the file from there. Successfully loaded files are stored locally, so that the next access does not require a remote request.

Configuration happens through the extension settings in the install tool. Typically a remote source is set up with a base URL, optionally with HTTP basic auth credentials. For setups with CDN or S3, this path can also serve as a source. The extension supports several sources, which is helpful for more complex scenarios with separate asset servers.

What matters is that filefill only works passively. The extension does not preload anything but only reacts to concrete file requests. That makes it frugal in resource use and unobtrusive in operation. Integration with DDEV, Docker Compose or Lando is trivial because the extension needs no additional services.

Common problems and solutions

The first problem is access restrictions. If the live server delivers images only for logged-in users or protects certain paths via htaccess, filefill cannot reload them without further ado. The solution lies in the correct configuration of HTTP authentication and, where needed, a whitelist rule on the live server that grants the development environment access to the fileadmin path.

Second problem: accidental use in production. If filefill is active in a live environment and the remote source is the same environment, a dangerous recursion is created. The extension should never run in production. The pragmatic solution is to keep filefill only in the Composer “require-dev” block and activate it via environment variables rather than through the install tool.

Third problem: inconsistent file states. When the live system replaces a file but the local copy is already cached, the developer sees the old version. The solution is an occasional clean-out of the local fileadmin or a cache busting via the remote source. For day-to-day work, this is rarely a problem because file names usually change on replacement.

Migration and version compatibility

filefill is compatible with TYPO3 v11, v12 and v13 and is actively maintained. On upgrades, the extension version should match the TYPO3 version, because the FAL event system has seen minor changes between v11 and v12. Anyone using the extension in existing development processes should briefly test on major upgrades whether all sources are still reachable.

A related solution is EXT:aus_driver_amazon_s3, which keeps fileadmin directly in an S3 bucket. The difference: aus_driver_amazon_s3 is a production solution, filefill is a development aid. Both complement each other: a project with S3 storage in production can use filefill locally to pull only the currently edited files from the bucket.

For agencies that use filefill in a standardised way, a documentation note in the project wiki pays off that explains how the extension is activated, which credentials are needed and how to proceed on problems. This reduces support effort on the team and makes onboarding of new developers reliable. On top of that, a short script that writes the right configuration on the setup of a new local environment is worth it.

Gosign installs and configures filefill in development environments and integrates the extension into DDEV and Docker setups, so that new project members are productive within minutes.