TYPO3 v15 dev-main snapshot ()

2026-08-10 22:31:09 +02:00
commit af8cc155b5
6818 changed files with 642608 additions and 0 deletions
@@ -0,0 +1,89 @@
+.. include:: /Includes.rst.txt
+
+.. _breaking-92609:
+
+==========================================================================
+Breaking: #92609 - Use controller classes when registering plugins/modules
+==========================================================================
+
+See :issue:`92609`
+
+Description
+===========
+
+Configuring plugins and modules via the following methods has changed in two important ways.
+
+* :php:`\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin`
+* :php:`\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule`
+
+Both methods expect to be provided with the arguments :php:`$extensionName` and :php:`$controllerActions`.
+:php:`configurePlugin` also allows the argument :php:`$nonCacheableControllerActions`.
+
+The first important change targets the :php:`$extensionName` argument.
+During the switch from underscore class names :php:`Tx_Extbase_Foo_Bar` to actual namespaced classes
+:php:`TYPO3\CMS\Extbase\Foo\Bar`, a vendor `TYPO3\CMS` has been introduced which had to be respected
+during the configuration of plugins. To make that possible the argument :php:`$extensionName` has been
+prepended with the vendor name, concatenated with dots.
+
+Before:
+
+.. code-block:: php
+
+   <?php
+
+   \TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin(
+       'TYPO3.CMS.Form', // $extensionName
+       'Formframework',
+       ['FormFrontend' => 'render, perform'],
+       ['FormFrontend' => 'perform'],
+       \TYPO3\CMS\Extbase\Utility\ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT
+   );
+
+Setting the vendor name has been marked as deprecated and must be omitted. Instead, the vendor name will be derived
+from the controller class namespace, which leads to the second important change.
+
+Both arguments :php:`$controllerActions` and :php:`$nonCacheableControllerActions` used controller aliases as
+array keys. The alias was the controller class name without the namespace and without the :php:`Controller`
+suffix. There were a lot of conventions and a custom autoloader mechanism before the introduction
+of the composer autoloader, which made it necessary to put controllers in a specific directory and to name
+the controller accordingly. As this is no longer the case, there is no need to guess the controller class name
+any longer. Instead, the configuration/registration is now done with fully qualified controller class names.
+
+After:
+
+.. code-block:: php
+
+   <?php
+
+   \TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin(
+       'Form',
+       'Formframework',
+       [\TYPO3\CMS\Form\Controller\FormFrontendController::class => 'render, perform'],
+       [\TYPO3\CMS\Form\Controller\FormFrontendController::class => 'perform'],
+       \TYPO3\CMS\Extbase\Utility\ExtensionUtility::PLUGIN_TYPE_CONTENT_ELEMENT
+   );
+
+
+Impact
+======
+
+Using non fully qualified class names during plugin/module registration will lead to malfunctioning plugins/modules at best.
+Probably an Exception will be thrown or a fatal error occurs during plugin/module dispatching.
+
+
+Affected Installations
+======================
+
+All installations that use these methods:
+
+* :php:`\TYPO3\CMS\Extbase\Utility\ExtensionUtility::configurePlugin()`
+* :php:`\TYPO3\CMS\Extbase\Utility\ExtensionUtility::registerModule()`
+
+
+Migration
+=========
+
+* Omit the vendor name in argument :php:`$extensionName`
+* Use fully qualified class names as array keys in arguments :php:`$controllerActions` and :php:`$nonCacheableControllerActions`
+
+.. index:: PHP-API, NotScanned, ext:extbase