Deprecation: #100335 - TCA config MM_insert_fields

See forge#100335


The TCA option MM_insert_fields has been marked as deprecated and should not be used anymore.


Using MM_insert_fields raises a deprecation level log message during TCA cache warmup. Its functionality is kept in TYPO3 v12 but will be removed in v13.

Affected installations

There may be extensions that use this option when configuring database MM relations. In most cases, the option can be removed. The migration section gives more details.


General scope: MM_insert_fields is used in combination with "true" database MM intermediate tables to allow many-to-many relations between two tables for group, select and sometimes even inline type fields.

A core example is the sys_category to tt_content relation, with sys_category_record_mm as intermediate table: The intermediate table has field uid_local (pointing to a uid of the "left" sys_category table), and uid_foreign (pointing to a uid of the "right" tt_content table). Note this specific relation also allows multiple different "right-side" table-field combinations, using the two additional fields tablenames and fieldname. All this is configured with TCA on the "left" and the "right" side table field, while table sys_category_record_mm has no TCA itself. Rows within the intermediate table are transparently handled by TYPO3 by the RelationHandler and extbase TCA-aware domain logic.

The MM_insert_fields now allows to configure a hard coded value for an additional column within the intermediate table. This is obsolete: There is no API to retrieve this value again, having a "stable" value in an additional column is useless. This config option should be removed from TCA definition.

Note on the related option MM_match_fields: This is important when an MM relation allows multiple "right" sides. In the example above, when a category is added to a tt_content record using the categories field, and when editing this relation from the "right" side (editing a tt_content record), then this option is used to select only relations for this tt_content.categories combination. The TCA column categories thus uses MM_match_fields to restrict the query. Note MM_match_fields is not set for the "left-side" sys_category items fields, this would indicate a TCA misconfiguration.

Various extensions in the wild did not get these details right, and often simply set both MM_insert_fields and MM_match_fields to the same values. Removing MM_insert_fields helps reducing confusion and simplifies this construct a bit. Affected extensions can simply remove the MM_insert_fields configuration and keep the MM_match_fields. Note the Core strives to further simplify these options and MM_match_fields may become fully obsolete in the future as well.