PHPackages konradmichalik/typo3-file-sync - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [File & Storage](/categories/file-storage) 4. / 5. konradmichalik/typo3-file-sync ActiveTypo3-cms-extension[File & Storage](/categories/file-storage) konradmichalik/typo3-file-sync ============================== File Sync - Synchronizes missing files between TYPO3 instances using configurable resource handlers. 0.2.2(2w ago)01.6k↑20.4%[1 issues](https://github.com/konradmichalik/typo3-file-sync/issues)[16 PRs](https://github.com/konradmichalik/typo3-file-sync/pulls)GPL-2.0-or-laterPHPPHP ~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0CI passing Since Mar 9Pushed 1mo agoCompare [ Source](https://github.com/konradmichalik/typo3-file-sync)[ Packagist](https://packagist.org/packages/konradmichalik/typo3-file-sync)[ RSS](/packages/konradmichalik-typo3-file-sync/feed)WikiDiscussions main Synced 1w ago READMEChangelog (5)Dependencies (55)Versions (47)Used By (0) [![Extension icon](Resources/Public/Icons/Extension.png)](Resources/Public/Icons/Extension.png) TYPO3 extension `typo3_file_sync` ================================= [](#typo3-extension-typo3_file_sync) [![Packagist Downloads](https://camo.githubusercontent.com/a4a467b7622628362a343ca8bcc14cb80b5bdd33819ead890b7276be3d12579d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b6f6e7261646d696368616c696b2f7479706f332d66696c652d73796e633f636f6c6f723d627269676874677265656e)](https://packagist.org/packages/konradmichalik/typo3-file-sync)[![TYPO3](https://camo.githubusercontent.com/1b6c390eac52f128bcf2640be62fe0e7cbbd2e99fbd02ea8d393a0ee0d71de95/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5459504f332d31332e3425323025374325323031342e302d6f72616e67652e737667)](https://camo.githubusercontent.com/1b6c390eac52f128bcf2640be62fe0e7cbbd2e99fbd02ea8d393a0ee0d71de95/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5459504f332d31332e3425323025374325323031342e302d6f72616e67652e737667)[![Supported PHP Versions](https://camo.githubusercontent.com/6b20bd9c6b15bcc2d79a8e230b0151152cf700dc948c5496e143939d66a38dbb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f6b6f6e7261646d696368616c696b2f7479706f332d66696c652d73796e632f7068703f6c6f676f3d706870)](https://packagist.org/packages/konradmichalik/typo3-file-sync)[![CGL](https://camo.githubusercontent.com/54b1f79494c5124093b4179dab1134e054cc3f1bab6dbb424403a78018e151b9/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6b6f6e7261646d696368616c696b2f7479706f332d66696c652d73796e632f63676c2e796d6c3f6c6162656c3d63676c266c6f676f3d676974687562)](https://github.com/konradmichalik/typo3-file-sync/actions/workflows/cgl.yml)[![Coverage](https://camo.githubusercontent.com/1681ad934883f2f5ca3ab367d991f4a1d9940a4a05ef40c984497298dcae5060/68747470733a2f2f696d672e736869656c64732e696f2f636f766572616c6c73436f7665726167652f6769746875622f6b6f6e7261646d696368616c696b2f7479706f332d66696c652d73796e633f6c6f676f3d636f766572616c6c73)](https://coveralls.io/github/konradmichalik/typo3-file-sync)[![Tests](https://camo.githubusercontent.com/43ac97186cd24720037176a89dc33550c3c674957c1bcb56e350e247d535cc59/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6b6f6e7261646d696368616c696b2f7479706f332d66696c652d73796e632f74657374732e796d6c3f6c6162656c3d7465737473266c6f676f3d676974687562)](https://github.com/konradmichalik/typo3-file-sync/actions/workflows/tests.yml)[![License](https://camo.githubusercontent.com/26f8b6541ea045cc1dbc2267208158b5a7ebbf5cf437c4b486d80fee9386f77e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d47504c2d2d322e302d2d6f722d2d6c617465722d626c75652e737667)](LICENSE.md) 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. 🔥 Installation -------------- [](#-installation) ### Requirements [](#requirements) - TYPO3 13.4 LTS or 14.0+ - PHP 8.2 – 8.5 - PHP extension `ext-gd` (for placeholder image generation) ### Composer [](#composer) [![Packagist](https://camo.githubusercontent.com/10ac55aef63f980e4ef41f0a17ce660b08cc06a804c8774ba20b4d0912179428/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b6f6e7261646d696368616c696b2f7479706f332d66696c652d73796e633f6c6162656c3d76657273696f6e266c6f676f3d7061636b6167697374)](https://packagist.org/packages/konradmichalik/typo3-file-sync)[![Packagist Downloads](https://camo.githubusercontent.com/a4a467b7622628362a343ca8bcc14cb80b5bdd33819ead890b7276be3d12579d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6b6f6e7261646d696368616c696b2f7479706f332d66696c652d73796e633f636f6c6f723d627269676874677265656e)](https://packagist.org/packages/konradmichalik/typo3-file-sync) ``` composer require konradmichalik/typo3-file-sync ``` ### TER [](#ter) [![TER version](https://camo.githubusercontent.com/f9b771d31f5d7c06b967a470ca7fd8b7f34296ffe8865183a8e4a0d6857f265f/68747470733a2f2f7479706f332d6261646765732e6465762f62616467652f7479706f335f66696c655f73796e632f76657273696f6e2f736869656c64732e737667)](https://extensions.typo3.org/extension/typo3_file_sync)[![TER downloads](https://camo.githubusercontent.com/43c2effb75c443422ac172fc45e56b3d5e840ceb01be4785e03f228a13ae2074/68747470733a2f2f7479706f332d6261646765732e6465762f62616467652f7479706f335f66696c655f73796e632f646f776e6c6f6164732f736869656c64732e737667)](https://extensions.typo3.org/extension/typo3_file_sync) Download the zip file from [TYPO3 extension repository (TER)](https://extensions.typo3.org/extension/typo3_file_sync). ### Setup [](#setup) ``` vendor/bin/typo3 extension:setup --extension=typo3_file_sync ``` ⚙️ Configuration ---------------- [](#️-configuration) File Sync can be configured in two ways: via the **TYPO3 backend** (per storage) or via **PHP configuration** (e.g. in `ext_localconf.php` or `additional.php`). ### Backend [](#backend) 1. Go to the **List** module and edit a **File Storage** record 2. Enable **File Sync** and configure the resource handlers ### PHP [](#php) ``` $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['typo3_file_sync']['storages'][1] = [ [ 'identifier' => 'remote_instance', 'configuration' => 'https://production.example.com', ], [ 'identifier' => 'placeholder_image', 'configuration' => '#CCCCCC, #969696', ], ]; ``` The array key (`1`) is the UID of the file storage. ✨ Resource Handlers ------------------- [](#-resource-handlers) ### Remote Instance [](#remote-instance) Fetches missing files from a remote TYPO3 instance via HTTP(S). The file path is appended to the configured base URL and requested with a `GET`; any non-`200` response is treated as "not available" so the next handler in the chain can take over. ``` 'identifier' => 'remote_instance', 'configuration' => 'https://production.example.com', ``` #### Basic Auth [](#basic-auth) If the remote instance is protected by `.htaccess` or similar, credentials can be included in the URL: ``` https://user:password@production.example.com ``` For environment variable support (works in both backend and PHP configuration), use `%env()%` placeholders: ``` https://%env(REMOTE_USER)%:%env(REMOTE_PASS)%@production.example.com ``` Warning `%env()%` placeholders resolve **any** environment variable of the process. Since File Sync is configured on `sys_file_storage` records, anyone able to edit a file storage can read arbitrary environment values (e.g. database credentials) by sending them to a remote host. Editing file storages is an admin-level task — keep it restricted to trusted backend administrators. #### Timeouts [](#timeouts) Requests use a connect timeout of `5` seconds and a request timeout of `15` seconds by default, so a slow or unreachable remote instance cannot block page rendering indefinitely. Both can be adjusted via PHP configuration: ``` 'identifier' => 'remote_instance', 'configuration' => [ 'url' => 'https://production.example.com', 'connect_timeout' => 5, 'timeout' => 15, ], ``` ### Placeholder Image [](#placeholder-image) Generates local placeholder images with configurable colors. Supports GD-based formats (`jpg`, `png`, `gif`, `webp`, `avif`) and `svg`. ``` 'identifier' => 'placeholder_image', 'configuration' => '#CCCCCC, #969696', // backgroundColor, textColor ``` The generated image displays the original file dimensions as a text overlay (e.g. `1920 x 1080`). Tip Chain both handlers to get real assets from production when available, falling back to a placeholder when they are not. 💡 CLI Commands -------------- [](#-cli-commands) ### Reset missing-file flags [](#reset-missing-file-flags) Resets the `missing` flag on `sys_file` records for all enabled storages or a specific one: ``` vendor/bin/typo3 file-sync:reset vendor/bin/typo3 file-sync:reset --storage=1 ``` ### Delete synced files [](#delete-synced-files) Removes files previously fetched by File Sync, optionally filtered by handler or storage: ``` vendor/bin/typo3 file-sync:delete --all vendor/bin/typo3 file-sync:delete --identifier=remote_instance vendor/bin/typo3 file-sync:delete --identifier=remote_instance --storage=1 ``` Warning `file-sync:delete --all` permanently removes all files that were fetched by any handler. Run `file-sync:reset` afterwards to allow them to be re-synced on next access. 🧩 Custom Resource Handlers -------------------------- [](#-custom-resource-handlers) Register a custom handler in your `ext_localconf.php`: ``` $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['typo3_file_sync']['resourceHandler']['my_handler'] = [ 'title' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:my_handler', 'config' => [ 'label' => 'LLL:EXT:my_extension/Resources/Private/Language/locallang.xlf:my_handler.config', 'config' => [ 'type' => 'input', ], ], 'handler' => \Vendor\MyExtension\Resource\Handler\MyHandler::class, ]; ``` The handler class must implement `RemoteResourceInterface`: ``` use KonradMichalik\Typo3FileSync\Resource\RemoteResourceInterface; use TYPO3\CMS\Core\Resource\FileInterface; class MyHandler implements RemoteResourceInterface { public function __construct(array|string|null $configuration) {} public function getFile(string $fileIdentifier, string $filePath, ?FileInterface $fileObject = null): mixed { // Return the file content as a string or stream resource, // or false if this handler cannot provide the file } } ``` 🙏 Acknowledgments ----------------- [](#-acknowledgments) This project is inspired by the great [filefill](https://github.com/IchHabRecht/filefill) extension. 🧑‍💻 Contributing ---------------- [](#‍-contributing) Please have a look at [`CONTRIBUTING.md`](CONTRIBUTING.md). ⭐ License --------- [](#-license) This project is licensed under [GNU General Public License 2.0 (or later)](LICENSE.md). ### Health Score 47 — FairBetter than 93% of packages Maintenance94 Actively maintained with recent releases Popularity21 Limited adoption so far Community6 Small or concentrated contributor base Maturity55 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~21 days Total 8 Last Release 14d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/11557705846f24da32a0e6e75c460db505c1b847f081ddaa3d27f3ea27f4097b?d=identicon)[konradmichalik](/maintainers/konradmichalik) --- Top Contributors [![konradmichalik](https://avatars.githubusercontent.com/u/4558190?v=4)](https://github.com/konradmichalik "konradmichalik (92 commits)") --- Tags typo3typo3-extension ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/konradmichalik-typo3-file-sync/health.svg) ``` [![Health](https://phpackages.com/badges/konradmichalik-typo3-file-sync/health.svg)](https://phpackages.com/packages/konradmichalik-typo3-file-sync) ``` ### Alternatives [typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.8M674](/packages/shopware-core)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 86337.5k](/packages/flow-php-flow)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k6.0M778](/packages/sylius-sylius)[typo3/cms-core TYPO3 CMS Core 3313.6M5.6k](/packages/typo3-cms-core)[shopware/platform The Shopware e-commerce core 3.4k1.5M3](/packages/shopware-platform) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)