Review main Merged Breaking

95980[!!!][FEATURE] Configure file storages in a file, not the database

Benni Mack CR +2 V +2 Nightmare +4722 −1649 updated 10/15/26, 15:20

Commit message

File storages define which directories of the server and which
remote buckets TYPO3 reads, writes and deletes in, and with which
credentials. Since the File Abstraction Layer was introduced in 2012
and released with TYPO3 6.0, fourteen years ago, they have been
records of the table sys_file_storage, edited through FormEngine
like content. I was the original author of that decision, and it
was a mistake: storages are configuration, not content. The Core has
improved since then, with structured YAML configuration,
placeholders, the Environment API and a project root separated from
the public directory, which is what makes this move possible now.

Storages are now defined in config/system/file-storages.yaml
(typo3conf/system/file-storages.yaml in classic mode). The file is
optional: without it, one local storage for the fileadmin directory
with identifier 1 is assumed, exactly what was auto-created so far.
The table, its TCA, the record form and the permission preset
entries are removed. An upgrade wizard writes existing records into
the file before the database analyzer drops the table.

This changes three things for good:

* A storage definition is not for regular admins. Changing a base
  path or a bucket can expose or destroy data no backend permission
  was meant to cover. The file is only reachable for whoever
  maintains config/system/: system maintainers, deployment tooling
  and upgrade code.
* A storage definition depends on the environment. Credentials and
  paths differ between local, staging and production and belong to
  the deployment, not to a database dump. The file supports %env()%
  placeholders and imports like the site configuration.
* A storage definition starts at the project root. Relative base
  paths of local storages resolve against the project path instead
  of the public directory, so a storage outside the web root no
  longer needs an absolute path.

EXT:impexp no longer imports the storage records of an export file.
Exports carry name, driver and base path of each storage. Each is
mapped to the local storage with the same resolved base path, or to
the default storage with a warning, and files are written there.

The numeric identifier stays the key everywhere it is persisted.
Driver registration is unchanged, only the FlexForm data structure
loses its consumer. ResourceStorage receives the normalized
definition, getStorageRecord() is deprecated, as is
StorageRepository->createLocalStorage() in favour of
addLocalStorage(), and the runtime "permanently offline" state moves
into the hash cache, as no record is left to write it into.

Review

  • Code review CR +2 Done
    • Benni Mack +2
    • Oli Bartsch +1
    • Wouter Wolters +1
  • Verified V +2 Done
    • Benni Mack +2
    • Oli Bartsch +1
    • Wouter Wolters +1
    • core-ci +1 CI

Issues 1

Files 159

Show 139 more files

Review log 2333

Show 68 earlier messages
  1. Benni Mack uploaded patch set 1 09/22/26, 17:51

  2. core-ci voted on patch set 1 V -1 09/22/26, 18:03 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/109004

  3. Benni Mack uploaded patch set 2 V -1 09/23/26, 12:31

  4. core-ci voted on patch set 2 V +1 09/23/26, 12:48 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/109053

  5. Garvin Hicking commented on patch set 2 09/24/26, 06:31

    Did you by chance evaluate the option to use a "shadow" database table sys_file_storage, which synchronizes from the YAML file (on cache:flush for example)? This would make it less breaking as custom extensions that JOIN on sys_file_storages could still work, and a database query reading files would be able to retrieve all information from the SQL/DB instead of needing to inject YAML-parsed data into it to resolve storage properties. In general I do see a lot of advantages being able to "deploy" these storage definitions. 😊
  6. Benni Mack commented on patch set 2 09/24/26, 12:59

    Reply

    well, I didn't. I see extensions extending the DB table, and I'd rather provide them with better APIs (like a new Settings API-based enhancement), and better support for their features (now we now what is used in FAL, after 14 years) than creating a half-baked shim that people can't really jump into.
  7. Garvin Hicking commented on patch set 2 09/25/26, 13:47

    Reply

    Alright. Well, then let's test it like it is now and gather some feedback!
  8. Benni Mack uploaded patch set 3 V +1 09/25/26, 16:52

  1. Benni Mack marked it ready for review 09/25/26, 17:04

  2. core-ci voted on patch set 3 V -1 09/25/26, 17:06 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/109274

  3. Benni Mack uploaded patch set 4 V -1 09/25/26, 17:10

  4. core-ci voted on patch set 4 V +1 09/25/26, 17:22 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/109279

  5. Benni Mack uploaded patch set 5 V +1 10/02/26, 13:46

  6. core-ci voted on patch set 5 V -1 10/02/26, 13:57 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/109947

  7. Benni Mack rebased onto patch set 6 V -1 10/07/26, 04:45

  8. core-ci voted on patch set 6 V -1 10/07/26, 09:59 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/110283

  9. Benni Mack uploaded patch set 7 V -1 10/08/26, 05:50

  10. core-ci voted on patch set 7 V -1 10/08/26, 06:05 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/110440

  11. Oli Bartsch uploaded patch set 8 V -1 10/08/26, 10:02

  12. core-ci voted on patch set 8 V +1 10/08/26, 10:12 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/110478

  13. Oli Bartsch commented on patch set 8 CR +1 V +1 10/08/26, 10:20

    Hey Benni, I pushed a new patchset, making CI green. I also made some changes, while mostly hardened the upgrade wizard: it now skips deleted records, copes with several or no default storages, keeps a single storage with a uid other than 1 and also finds the renamed zzz_deleted_table. If the file already exists, it reports what is missing instead of skipping silently. The writer respects imports, writes atomically and rolls back on a mismatch. Reading is more tolerant, so one broken entry only takes that storage offline. createLocalStorage() keeps its old signature as a deprecated wrapper around the new addLocalStorage(), and impexp exports the storage metadata again so imports can map by base path. I also fixed the tests that landed in main after PS4. A few things I left for you to decide: whether an empty file should really mean "fileadmin only", whether unreferenced identifiers may be reused, whether runtime writes should be enforced as CLI-only instead of just documented, and whether storages should be sorted by name again. I suggest to get this one in first and rebase 95073, 93647 and 95956 on top of it. Does that work for you?
  14. Benni Mack uploaded patch set 9 CR +1 V +1 10/14/26, 07:13

  15. Benni Mack commented on patch set 9 10/14/26, 07:14

    Reply

    I did the following things: - Cache - identifiers are not reused - storages are sorted by name - updated the RST
  16. core-ci voted on patch set 9 V +1 10/14/26, 07:20 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/111048

  17. Oli Bartsch voted on patch set 9 CR +1 V +1 10/14/26, 13:37

  18. Wouter Wolters commented on patch set 9 10/14/26, 20:35

    I think this change is good. The only downside is that I think you want these files in your version control. Migration is running on a production env which, if everything is good, does not have GIT or the like installed. So we force each installation to do a pre migration on an environment they can use GIT or copy the files from the production environment.

    FileStorageConfiguration.php:45

    typed constants are possible now

    pages-and-ttcontent.xml:352

    indentation is different and in all other XML files
  19. Benni Mack uploaded patch set 10 CR +1 V +1 10/15/26, 10:17

  20. Benni Mack commented on patch set 10 10/15/26, 10:17

    FileStorageConfiguration.php:45 Reply

    Done

    pages-and-ttcontent.xml:352 Reply

    This is actually from flexArray2Xml
  21. core-ci voted on patch set 10 V +1 10/15/26, 10:25 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/111177

  22. Oli Bartsch voted on patch set 10 CR +1 V +1 10/15/26, 10:29

  23. Wouter Wolters voted on patch set 10 CR +1 V +1 10/15/26, 15:19

  24. Benni Mack commented on patch set 10 CR +2 V +2 10/15/26, 15:20

    Thank you. This is a huge step in FAL 2.0 :)
  25. Benni Mack merged patch set 11 10/15/26, 15:20