README

TYPO3 extension typo3_file_sync

A lightweight TYPO3 extension that synchronizes missing files on demand: either by fetching them from a remote instance or by generating local placeholder images.

Tip

Typical use case: staging systems or local development environments that get refreshed from production on a regular basis (e.g. via a database sync) without copying the full file storage. Missing files are fetched (or replaced with a placeholder) the moment they're actually requested, instead of shipping every asset on each refresh.

✨ Features

• Remote instance fetching: pull missing files from a remote TYPO3 instance on demand
• Placeholder image generation: generate local placeholder images (GD and SVG) when no remote instance is configured or reachable
• CLI commands: reset missing-file flags or delete previously synced files
• Deferred image loading (experimental): render a placeholder immediately and swap in the real file after page load, with an optional blurred preview stage
• Custom resource handlers: implement your own remote source

🔥 Installation

Requirements

• TYPO3 13.4 LTS or 14.3 LTS
• PHP 8.2 to 8.5
• PHP extension ext-gd (for placeholder and preview image generation; previews additionally need a GD build with WebP support)

Composer

composer require konradmichalik/typo3-file-sync

TER

Download the zip file from TYPO3 extension repository (TER).

Setup

vendor/bin/typo3 extension:setup --extension=typo3_file_sync

Upgrading

Run the same command after every update, or use the database analyser in the Install Tool. This release adds the column tx_typo3_file_sync_failed to sys_file, and deferred image loading needs it: between composer update and the schema update every materialize request fails with a database error and answers 500, so every deferred image stays a grey placeholder.

🚀 Quick start

Configure a storage in ext_localconf.php (or additional.php) to fetch missing files from a remote instance:

$GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['typo3_file_sync']['storages'][1] = [
    [
        'identifier' => 'remote_instance',
        'configuration' => 'https://production.example.com',
    ],
];

The array key (1) is the UID of the file storage. See Configuration for the backend UI alternative, chaining handlers, and the full option set.

📚 Documentation

💎 Credits

This project is inspired by the great filefill extension. File Sync targets TYPO3 13.4 LTS and 14.0+, generates placeholder images (GD and SVG) fully locally without relying on an external service like Placehold.co, and adds CLI commands for resetting and deleting synced files.

🧑‍💻 Contributing

Please have a look at CONTRIBUTING.md.

⭐ License

This project is licensed under GNU General Public License 2.0 (or later).