[TASK] Deprecate plugin content element and plugin subtypes (list_typ…

…e) (#4821)

* [TASK] Deprecate plugin content element and plugin subtypes (list_type)

Depends on TYPO3-Documentation/TYPO3CMS-Reference-TCA#1183

Resolves: TYPO3-Documentation/Changelog-To-Doc#1071

Releases: main, 13.4


---------

Co-authored-by: Stefan Frömken <123929835+sfroemkenjw@users.noreply.github.com>

Documentation/ApiOverview/ContentElements/ContentElementsWizard.rst

@@ -64,7 +64,7 @@ the available groups.
 Plain content elements or plugins
 =================================
 
-You can add a content element or plain plugin (non-extbase) using method
+You can add a content element or plain plugin (no Extbase) using method
 `ExtensionManagementUtility::addPlugin() <https://api.typo3.org/main/classes/TYPO3-CMS-Core-Utility-ExtensionManagementUtility.html#method_addPlugin>`__:
 of class :php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility`.
 
@@ -74,11 +74,12 @@ of class :php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility`.
 The key `value` in the parameter `$itemArray` is used as key of the newly added
 content element representing the plugin.
 
-When you are using `CType` (recommended) for parameter `$type` the content
+When you are using `CType` for parameter `$type` the content
 element is added to the select item list of column `CType` in table `tt_content`.
 
-If you are using the default `list_type` for the parameter it is added as
-subtype.
+..  deprecated:: 13.4
+    Using the default `list_type` for the parameter is deprecated. All content
+    elements and plugins should be added with string `CType` for parameter `$type`.
 
 This method supplies some default values:
 

Documentation/ApiOverview/ContentElements/CustomBackendPreview.rst

@@ -118,23 +118,12 @@ approaches:
     This specifies the preview renderer only for records of type :php:`$type` as
     determined by the :ref:`type field <t3tca:types>` of your table.
 
-#.  Table and field have a :php:`subtype_value_field` TCA setting
+..  deprecated:: 13.4
+    Registration of subtypes has been deprecated. Registration of custom
+    types should therefore always be done by using
+    :confval:`record types <t3tca:ctrl-type>`.
 
-    If your table and field have a
-    :ref:`subtype_value_field <t3tca:types-properties-subtype-value-field>` TCA
-    setting (like :php:`tt_content.list_type` for example) and you want to
-    register a preview renderer that applies only when that value is selected
-    (assume, when a certain plugin type is selected and you can't match it with
-    the "type" of the record alone):
-
-    ..  code-block:: php
-
-        $GLOBALS['TCA'][$table]['types'][$type]['previewRenderer'][$subType]
-            = MyVendor\MyExtension\Preview\MyPreviewRenderer::class;
-
-    Where :php:`$type` is, for example, :php:`list` (indicating a plugin) and
-    :php:`$subType` is the value of the :php:`list_type` field when the type of
-    plugin you want to target is selected as plugin type.
+    See also :ref:`t3tca:migration-subtype-previewrenderer`.
 
 ..  note::
     The :ref:`recommended location <extension-configuration-tca>` is in the

Documentation/ApiOverview/ContentElements/Index.rst

@@ -19,6 +19,7 @@ created, how existing content elements or plugins can be customized etc.
     CustomBackendPreview
     ContentElementsWizard
     BestPractices
+    MigrationListType
 
 ..  _cePluginsIntroduction:
 
@@ -143,8 +144,9 @@ An Extbase plugin is configured for the frontend with
 ..  literalinclude:: _Plugins/_ext_localconf_extbase_plugin.php
     :caption: EXT:my_extension/ext_localconf.php
 
-By using `ExtensionUtility::PLUGIN_TYPE_PLUGIN` as fifth parameter is is also
-possible to add the plugin as a list type. See :ref:`plugins-list_type`.
+..  deprecated:: 13.4
+    Setting the fifth parameter to any value but `ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT`
+    is deprecated. See :ref:`plugins-list_type-migration`.
 
 Method :php:`ExtensionUtility::configurePlugin()` also takes care of registering
 the plugin for frontend output in TypoScript using an object of type
@@ -183,12 +185,9 @@ To register such a plugin as content element you can use function
 ..  literalinclude:: _Plugins/_tt_content_plugin.php
     :caption: EXT:my_extension/Configuration/TCA/Overrides/tt_content.php
 
-By using `'list_type'` as second parameter is is also possible to add the plugin
-as a list type. See :ref:`plugins-list_type`.
-
-**Plugins** are a specific type of content elements. Plugins use the CType='list'.
-Each plugin has its own plugin type, which is used in the database field
-tt_content.list_type. The list_type could be understood as subtype of CType.
+..  deprecated:: 13.4
+    Setting the second parameter to `list_type`
+    is deprecated. See :ref:`plugins-list_type-migration`.
 
 ..  _plugins-characteristics:
 
@@ -215,32 +214,6 @@ has a plugin that allow frontend users, stored in table `fe_users` to log into
 the website. :composer:`typo3/cms-indexed-search` has a plugin that can be
 used to search in the index and display search results.
 
-..  _plugins-list_type:
-
-CType vs list_type plugins
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Historically it was common to add plugins as a list type to the content element
-types. In this case the column `CType` is set to `'list'` for all plugins while
-the field `list_type` contains the key of the actual plugin.
-
-As different plugins need different fields in the backend form this let to
-the creation of all type of complicated TCA constructs to influence the
-behaviour of backend forms for plugins.
-
-The existence of the `list_type` also made a separate layer of content element
-definitions in the TypoScript necessary.
-
-Therefore the `list_type` complicates registration and configuration of plugins
-while it poses no advantages. Therefore it is recommended to always use the
-CType for new plugin types while the `list_type` is retained for now for
-backward compatibility.
-
-If you are refactoring the plugins of your extension, for example while getting
-rid of switchable controller actions it is recommended to migrate your plugins
-to use the CType. You should then supply a
-:ref:`upgrade wizard <upgrade-wizard-examples-switchable-controller-actions>`
-for easy migration for your users.
 
 ..  _plugins-editing:
 

Documentation/ApiOverview/ContentElements/MigrationListType.rst

@@ -0,0 +1,160 @@
+..  include:: /Includes.rst.txt
+..  _plugins-list-type:
+..  _plugins-list-type-migration:
+
+=========================================
+Migration: `list_type` plugins to `CType`
+=========================================
+
+..  deprecated:: 13.4
+    The plugin content element (:php:`list`) and the plugin sub types
+    field (:php:`list_type`) have been marked as deprecated in TYPO3 v13.4 and
+    will be removed in TYPO3 v14.0.
+
+Several steps are important in the migration from `list_type` plugins to `CType`
+plugins:
+
+*   Register plugins using the `CType` record type
+*   Create update wizard which extends :php:`\TYPO3\CMS\Install\Updates\AbstractListTypeToCTypeUpdate`
+    and add :php:`list_type` to :php:`CType` mapping for each plugin to migrate.
+*   Migrate possible FlexForm registration and add dedicated :php:`showitem` TCA
+    configuration
+*   Migrate possible `PreviewRenderer` registration in TCA
+*   Adapt possible content element wizard items in page TSconfig, where
+    :php:`list_type` is used
+*   Adapt possible content element restrictions in backend layouts or container
+    elements defined by third-party extensions like :t3ext:`content_defender`
+
+..  contents:: Table of content
+
+..  _plugins-list-type-migration-extbase:
+
+Migration example: Extbase plugin
+=================================
+
+..  _plugins-list-type-migration-extbase-configuration:
+
+1. Adjust the Extbase plugin configuration
+------------------------------------------
+
+Extbase plugins are usually registered using the utility method
+:php:`\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin()` in file
+:file:`EXT:my_extension/ext_localconf.php`.
+
+Add value `ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT` as fifth parameter,
+`$pluginType`, to the method :php:`ExtensionUtility::configurePlugin()`:
+
+..  literalinclude:: _Migration/_ext_localconf.php.diff
+    :caption: EXT:examples/ext_localconf.php (difference)
+
+If the fourth parameter, `$nonCacheableControllerActions` was missing you can
+set it to an empty array, the default value.
+
+It is theoretically possible that the extension author did not use this utility
+method. In that case you have to change the TypoScript used to display your
+plugin manually. This step is similar to adjusting the TypoScript of a
+Core-based plugin.
+
+..  _plugins-list-type-migration-extbase-flexform:
+
+2. Adjust the registration of FlexForms and additional fields
+-------------------------------------------------------------
+
+..  literalinclude:: _Migration/_tca_registration.php.diff
+    :caption: EXT:examples/Configuration/TCA/Overrides/tt_content.php (difference)
+    :linenos:
+
+The `CType` based plugin does not inherit the default fields provided by the
+TCA of the content element "List". These where in many cases removed by
+using :confval:`subtypes_excludelist <t3tca:types-subtypes-excludelist>`.
+
+As these fields are not displayed automatically anymore you can remove this
+definition without replacement: Line 15 in the diff. If they have not been
+removed and are still needed, you will need to manually add them to your plugin type.
+
+The :confval:`subtypes_addlist <t3tca:types-subtypes-addlist>` was used to
+display the field containing the FlexForm, an possibly other fields in the
+`list_type` plugin. We remove this definition (Line 17) and replace it
+by using the utility method
+:php:`\TYPO3\CMS\Core\Utility\ExtensionManagementUtility::addToAllTCAtypes()`
+(Line 25-30).
+
+The utility method :php:`ExtensionManagementUtility::addPiFlexFormValue()`
+needs to be changed from using the first parameter for the `$pluginSignature`
+to using the third parameter. The first parameter requires a certain `list_type`
+setting it to the wildcard `*` allows all list types. The third parameter limits
+it to the `CType`.
+
+..  _plugins-list-type-migration-extbase-upgrade-wizard:
+
+3. Provide an upgrade wizard
+----------------------------
+
+..  versionadded:: 13.4
+    If your extension also should support TYPO3 version 12.4 or even 11.5 see
+    Example: :ref:`plugins-list-type-migration-core-plugin-migration`.
+
+You can extend class :php-short:`TYPO3\CMS\Install\Updates\AbstractListTypeToCTypeUpdate`
+to provide a custom upgrade wizard that moves existing plugins from the
+`list_type` definition to the `CType` definition. The resulting upgrade wizard
+will even adjust backend user permissions for the defined plugins:
+
+..  include:: /CodeSnippets/Extbase/Upgrades/ExtbasePluginListTypeToCTypeUpdate.rst.txt
+
+..  _plugins-list-type-migration-extbase-replace:
+
+4. Search your code and replace any mentioning of `list_type`
+-------------------------------------------------------------
+
+Search your code. If you used the `list_type` of you plugin in any custom
+database statement or referred to the according
+
+Search your TCA definitions for any use of the now outdated configuration
+options
+
+..  _plugins-list-type-migration-core:
+
+Migration example: Core-based plugin
+====================================
+
+..  _plugins-list-type-migration-core-plugin-registration:
+
+1.  Adjust the plugin registration
+----------------------------------
+
+..  literalinclude:: _Migration/_non_extbase_tca.diff
+    :caption: EXT:my_extension/Configuration/TCA/tt_content.php (diff)
+
+..  _plugins-list-type-migration-core-plugin-typoscript:
+
+2.  Adjust the TypoScript of the plugin
+---------------------------------------
+
+If your plugin was rendered using :composer:`typo3/cms-fluid-styled-content` you are
+probably using the top level TypoScript object
+:ref:`tt_content <t3tsref:tlo-tt_content>` to render the plugin. The path to
+the plugin rendering needs to be adjusted as you cannot use the deprecated content
+element "list" anymore:
+
+..  literalinclude:: _Migration/_typoscript.diff
+    :caption: EXT:my_extension/Configuration/Sets/MyPluginSet/setup.typoscript (diff)
+
+..  _plugins-list-type-migration-core-plugin-migration:
+
+3.  Provide an upgrade wizard for automatic content migration for TYPO3 v13.4 and v12.4
+---------------------------------------------------------------------------------------
+
+If you extension only support TYPO3 v13 and above you can extend the Core class
+:php:`\TYPO3\CMS\Install\Updates\AbstractListTypeToCTypeUpdate`.
+
+If your extension also supports TYPO3 v12 and maybe even TYPO3 v11 you can use
+class :php:`Linawolf\ListTypeMigration\Upgrades\AbstractListTypeToCTypeUpdate`
+instead. Require via composer: :composer:`linawolf/list-type-migration` or
+copy the file into your extension using your own namespaces:
+
+..  literalinclude:: _Migration/PluginListTypeToCTypeUpdate.php
+    :caption: EXT:my_extension/Classes/Upgrades/PluginListTypeToCTypeUpdate.php
+
+If you also have to be compatible with TYPO3 v11, register the upgrade wizard
+manually:
+:ref:`Registering wizards for TYPO3 v11 <t3coreapi/11:upgrade-wizards-register>`.

Documentation/ApiOverview/ContentElements/_Migration/PluginListTypeToCTypeUpdate.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MyVendor\MyExtension\Upgrades;
+
+// composer req linawolf/list-type-migration
+use Linawolf\ListTypeMigration\Upgrades\AbstractListTypeToCTypeUpdate;
+use TYPO3\CMS\Install\Attribute\UpgradeWizard;
+
+#[UpgradeWizard('myExtensionPluginListTypeToCTypeUpdate')]
+final class PluginListTypeToCTypeUpdate extends AbstractListTypeToCTypeUpdate
+{
+    protected function getListTypeToCTypeMapping(): array
+    {
+        return [
+            'my_extension_pi1' => 'my_extension_pi1',
+            'my_extension_pi2' => 'my_extension_newpluginname',
+        ];
+    }
+
+    public function getTitle(): string
+    {
+        return 'Migrates my_extension plugins';
+    }
+
+    public function getDescription(): string
+    {
+        return 'Migrates my_extension_pi1, my_extension_pi2  from list_type to CType. ';
+    }
+}

Documentation/ApiOverview/ContentElements/_Migration/_ext_localconf.php.diff

@@ -0,0 +1,12 @@
+ use T3docs\Examples\Controller\FalExampleController;
+ use TYPO3\CMS\Extbase\Utility\ExtensionUtility;
+
+ ExtensionUtility::configurePlugin(
+     'Examples',
+     'HtmlParser',
+     [
+         HtmlParserController::class => 'index',
+     ],
++    [],
++    ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT,
+ );

Documentation/ApiOverview/ContentElements/_Migration/_non_extbase_tca.diff

@@ -0,0 +1,34 @@
+ $pluginSignature = 'examples_pi1';
+ $pluginTitle = 'LLL:EXT:examples/Resources/Private/Language/locallang_db.xlf:tt_content.examples_pi1.title';
+ $extensionKey = 'examples';
+ $flexFormPath = 'FILE:EXT:examples/Configuration/Flexforms/flexform_ds1.xml';
+
+ // Add the plugins to the list of plugins
+ ExtensionManagementUtility::addPlugin(
+     [$pluginTitle, $pluginSignature, '', 'plugin'],
+-    'list_type',
++    'CType',
+     $extensionKey,
+ );
+
+-// Disable the display of layout and select_key fields for the plugin
+-$GLOBALS['TCA']['tt_content']['types']['list']['subtypes_excludelist'][$pluginSignature]
+-    = 'layout,select_key,pages';
+-
+-// Activate the display of the plug-in flexform field and set FlexForm definition
+-$GLOBALS['TCA']['tt_content']['types']['list']['subtypes_addlist'][$pluginSignature] = 'pi_flexform';
+
++// Activate the display of the FlexForm field
++ExtensionManagementUtility::addToAllTCAtypes(
++    'tt_content',
++    '--div--;Configuration,pi_flexform,',
++    $pluginSignature,
++    'after:subheader',
++);
+
+ ExtensionManagementUtility::addPiFlexFormValue(
+-    $pluginSignature,
++    '*',
+     $flexFormPath,
++    $pluginSignature,
+ );