Deprecation: #108653 - Form file-based storage deprecated

Description

File-based form storage (YAML files stored via file mounts) in EXT:form has been deprecated in favor of database storage.

Since TYPO3 v14.2, the EXT:form module stores form definitions as records in the form_definition database table. This approach provides simpler setup, integrates better with the TYPO3 permission system, and eliminates the need for file mounts and file system configuration.

The following components are deprecated and will be removed in TYPO3 v15.0:

\TYPO3\CMS\Form\Storage\FileMountStorageAdapter – the storage adapter for FAL file mount-based form persistence
The YAML configuration option persistenceManager.allowedFileMounts – configuring allowed file mounts for form storage

See Feature: #108653 - Database storage for form extension for the new database storage approach.

An upgrade wizard as well as a CLI command are available to migrate existing file-based form definitions to the database: System > Upgrade > Upgrade Wizard > Migrate file-based forms to database storage.

Note

YAML form files provided within extension directories (persistenceManager.allowedExtensionPaths) still work as before and are not affected by this deprecation until further concepts are evaluated.

Impact

File-based form storage will continue to work without any functional changes during the deprecation period. However, it will be removed in TYPO3 v15.0.

An upgrade wizard is available to check whether file-based forms exist and to migrate them to database storage. Run the wizard regularly to verify your migration status.

Affected installations

All installations that:

Store form definitions as YAML files in file mounts (for example, 1:/form_definitions/)
Use the persistenceManager.allowedFileMounts configuration option in their form setup YAML with one or more mount points configured

Migration

Warning

If your installation uses file mount–based permission separation (i.e., different backend user groups have access to different form storage folders to isolate which forms they can see and edit), an equivalent access control mechanism for database-stored forms is not yet available.

In this case, it is recommended to not migrate at this time. The file-based storage will continue to work without functional changes during the entire deprecation period. A dedicated permission feature for database storage is planned for a future release.

Run the upgrade wizard Migrate file-based forms to database storage in the System > Upgrade module. This wizard:
- Copies all file-based form definitions into the form_definition database table
- Updates all tt_content FlexForm references (persistenceIdentifier) to point to the new database records
- Deletes the original YAML files after successful migration
If the form_definition table does not exist yet, run System > Maintenance > Analyze Database first.

Important

The upgrade wizard only updates references in tt_content (CType form_formframework). If your installation stores form persistence identifiers in custom database tables or FlexForm fields outside tt_content (e.g., through third-party extensions), these references are not updated automatically and must be migrated manually.
After verifying that all forms work correctly from the database, remove the allowedFileMounts configuration from your YAML setup:

Before (deprecated):

EXT:my_extension/Configuration/Yaml/FormSetup.yaml
```
persistenceManager:
  allowedFileMounts:
    10: '1:/form_definitions/'
```
Copied!
After:

To explicitly disable file mount storage, set allowedFileMounts to null (~):

EXT:my_extension/Configuration/Yaml/FormSetup.yaml
```
persistenceManager:
  allowedFileMounts: ~
```
Copied!
Optionally, if the upgrade wizard did not delete the YAML files (e.g., due to file permission issues), delete them manually from the file system after confirming that the migration was successful.

Alternatively, the CLI command form:definition:transfer can be used to transfer forms between storage types:

# Transfer all file mount forms to database
bin/typo3 form:definition:transfer --source=filemount --target=database

# Move (transfer + delete source) in one step
bin/typo3 form:definition:transfer --source=filemount --target=database --move

# Preview without changes
bin/typo3 form:definition:transfer --source=filemount --target=database --dry-run