How to migrate switchableControllerActions in a TYPO3 Extbase extension to single plugins

TL;DR - I created this TYPO3 update wizard which migrates plugins and Extbase plugin settings for each former switchable controller actions configuration entry.

Since switchableControllerActions in Extbase plugins have been deprecated in TYPO3 10.4 and will be removed in either TYPO3 11 but most likely 12, I decided to remove switchableControllerActions in my TYPO3 Extbase extensions already with the upcoming versions that will be compatible with TYPO3 11.

In this blogpost I will show, how extension authors can add a smooth migration path to their existing extensions by adding an update wizard which migrates all existing plugin settings, so users do not have to change plugin settings manually.

As a starting point lets have a look at my TYPO3 extension Plain FAQ, which is a very simple Extbase extension with one plugin, that has 3 switchableControllerActions.

Source: Flexform for Pi1

• Faq->list;Faq->detail
• Faq->list
• Faq->detail

For all 3 switchableControllerActions, I created 3 individual plugins (Pilistdetail, Pilist, Pidetail) which handle the action(s) of each switchable controller action from the list above.

For each new plugin, I added an individual FlexForm file which holds the available settings for the plugin. This can be done by duplicating the old FlexForm (Pi1 in this case) and removing those settings, which are not available in the new plugin. Also display conditions based switchableControllerActions must be removed.

Finally I created a new item group for the Plugins of the extension, so all plugins are grouped as shown on the screenshot below.

This is basically all work that needs to be done on code side in order split the old plugin to the new plugins.

Migration of existing plugins

To be able to migrate all existing plugins and settings to the new plugins, I created a custom upgrade wizard that takes care of all required tasks. Those tasks are as following:

• Determine, which tt_content record need to be updated
• Analyse existing Plugin (field: list_type) and switchableControllerActions in FlexForm (field: pi_flexform)
• Remove non-existing settings and switchableControllerAction from FlexForm by comparing settings with new FlexForm structure of target plugin
• Update tt_content record with new Plugin and FlexForm

As a result, a SwitchableControllerActionsPluginUpdater has been added to the extension. It takes care of all mentioned tasks and has a configuration array which contains required settings (source plugin, target plugin and switchableControllerActions) for the migration.

private const MIGRATION_SETTINGS = [
    [
        'sourceListType' => 'plainfaq_pi1',
        'switchableControllerActions' => 'Faq->list;Faq->detail',
        'targetListType' => 'plainfaq_pilistdetail'
    ],
    [
        'sourceListType' => 'plainfaq_pi1',
        'switchableControllerActions' => 'Faq->list',
        'targetListType' => 'plainfaq_pilist'
    ],
    [
        'sourceListType' => 'plainfaq_pi1',
        'switchableControllerActions' => 'Faq->detail',
        'targetListType' => 'plainfaq_pidetail'
    ],
];

So basically, one configuration entry has to be added for each switchable controller action setting of the old plugin. The wizard determines the new FlexForm settings using configured TCA, removes all non-existing settings (which is important, since TYPO3 will pass every setting available in pi_flexform to Extbase controllers and Fluid templates) and changes the “old” Plugin to the new one.

The update wizard can possibly also be used in other Extbase extensions, since the MIGRATION_SETTINGS are the only configuration options that need to be changed.

The required changes for the complete removal of switchableControllerActions is available in this commit.