From 454771f7c803d28ec7e1eb3c54ba10c16e76f8f3 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 1 Dec 2025 06:54:27 +0100 Subject: [PATCH 1/3] [TASK] Allow shipping upgrade wizards w/o requiring EXT:install Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1496 Releases: main --- .../UpdateWizards/Concept.rst | 9 +-- .../UpdateWizards/Creation.rst | 61 +++++++++++++------ .../UpdateWizards/_ExampleUpgradeWizard.php | 5 +- ...witchableControllerActionUpgradeWizard.php | 4 +- 4 files changed, 52 insertions(+), 27 deletions(-) diff --git a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Concept.rst b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Concept.rst index 61a9041a38..cf77433051 100644 --- a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Concept.rst +++ b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Concept.rst @@ -26,14 +26,11 @@ Each wizard is able to check pre-conditions to prevent execution, if nothing has to be updated. The wizard can log information and executed SQL statements, that can be displayed after execution. -Best practice -============= +.. rubric:: Best practice Each extension can provide as many upgrade wizards as necessary. Each wizard should perform exactly one specific update. -Examples -======== +.. rubric:: Examples -The TYPO3 Core itself provides upgrade wizards inside -:t3src:`install/Classes/Updates/`. +See `Examples for common upgrade wizards `_. diff --git a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst index dbe3b924ab..d46acbddf1 100644 --- a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst +++ b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst @@ -11,10 +11,15 @@ Implementing an upgrade wizard ============================== -.. versionchanged:: 13.0 - The registration via - :php:`$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/install']['update']` - in :file:`ext_localconf.php` was removed in TYPO3 v13. +.. deprecated:: 14.0 + The attribute :php:`\TYPO3\CMS\Install\Attribute\UpgradeWizard` has been + deprecated in favour of :php:`\TYPO3\CMS\Core\Attribute\UpgradeWizard`. + + The interfaces and classes used for upgrade wizards have been moved from + namespace `\TYPO3\CMS\Install\Updates` to `\TYPO3\CMS\Core\Upgrades`. + + Using the old locations is deprecated in v14 but can be used to provide + compatibility with both TYPO3 v13 and v14. To create an upgrade wizard you have to add a class which implements the :ref:`UpgradeWizardInterface `. @@ -35,12 +40,20 @@ The class *may* implement other interfaces (optional): UpgradeWizardInterface ====================== +.. deprecated:: 14.0 + :php:`\TYPO3\CMS\Install\Updates\UpgradeWizardInterface` has been deprecated, + implement :php:`\TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface` once dropping + TYPO3 v13 support. + + The attribute :php:`\TYPO3\CMS\Install\Attribute\UpgradeWizard` has been + deprecated in favour of :php:`\TYPO3\CMS\Core\Attribute\UpgradeWizard`. + Each upgrade wizard consists of a single PHP file containing a single PHP class. -This class has to implement :php:`TYPO3\CMS\Install\Updates\UpgradeWizardInterface` +This class has to implement :php:`\TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface` and its methods. The registration of an upgrade wizard is done directly in the class by adding -the class attribute :php:`\TYPO3\CMS\Install\Attribute\UpgradeWizard`. The +the class attribute :php:`\TYPO3\CMS\Core\Attribute\UpgradeWizard`. The :ref:`unique identifier ` is passed as an argument. .. literalinclude:: _ExampleUpgradeWizard.php @@ -68,16 +81,16 @@ Method :php:`getPrerequisites()` can define dependencies before it can be performed. Currently, the following prerequisites exist: - * `DatabaseUpdatedPrerequisite`: + * :php-short:`\TYPO3\CMS\Core\Upgrades\DatabaseUpdatedPrerequisite`: Ensures that the database table fields are up-to-date. - * `ReferenceIndexUpdatedPrerequisite`: + * :php-short:`\TYPO3\CMS\Core\Upgrades\ReferenceIndexUpdatedPrerequisite`: The reference index needs to be up-to-date. .. code-block:: php :caption: EXT:my_extension/Classes/Upgrades/ExampleUpgradeWizard.php - use TYPO3\CMS\Install\Updates\DatabaseUpdatedPrerequisite; - use TYPO3\CMS\Install\Updates\ReferenceIndexUpdatedPrerequisite; + use TYPO3\CMS\Core\Upgrades\DatabaseUpdatedPrerequisite; + use TYPO3\CMS\Core\Upgrades\ReferenceIndexUpdatedPrerequisite; /** * @return string[] @@ -158,12 +171,17 @@ Some examples: Marking wizard as done ====================== +.. deprecated:: 14.0 + :php:`\TYPO3\CMS\Install\Updates\RepeatableInterface` has been deprecated, + implement :php:`\TYPO3\CMS\Core\Upgrades\RepeatableInterface` once dropping + TYPO3 v13 support. + As soon as the wizard has completely finished, for example, it detected that no upgrade is necessary anymore, the wizard is marked as done and will not be checked anymore. To force TYPO3 to check the wizard every time, the interface -:t3src:`install/Classes/Updates/RepeatableInterface.php` has to be implemented. +:php:`\TYPO3\CMS\Core\Upgrades\RepeatableInterface` has to be implemented. This interface works as a marker and does not force any methods to be implemented. @@ -175,23 +193,24 @@ implemented. Generating output ================= -The :php:`ChattyInterface` can be implemented for wizards which should generate -output. :t3src:`install/Classes/Updates/ChattyInterface.php` uses the Symfony -interface `OutputInterface`_. - -.. _OutputInterface: https://github.com/symfony/symfony/blob/5.4/src/Symfony/Component/Console/Output/OutputInterface.php +The :php:`\TYPO3\CMS\Install\Updates\ChattyInterface` can be implemented for +wizards which should generate +output. It uses the Symfony interface +:php:`\Symfony\Component\Console\Output\OutputInterface`. Classes using this interface must implement the following method: .. code-block:: php :caption: vendor/symfony/console/Output/OutputInterface.php + use Symfony\Component\Console\Output\OutputInterface; + /** * Setter injection for output into upgrade wizards */ public function setOutput(OutputInterface $output): void; -The class :t3src:`install/Classes/Updates/DatabaseUpdatedPrerequisite.php` +The class :php:`\TYPO3\CMS\Core\Upgrades\DatabaseUpdatedPrerequisite` implements this interface. We are showing a simplified example here, based on this class: @@ -200,6 +219,8 @@ this class: :emphasize-lines: 8,10-13,20 use Symfony\Component\Console\Output\OutputInterface; + use TYPO3\CMS\Core\Upgrades\DatabaseUpdatedPrerequisite; + use TYPO3\CMS\Core\Upgrades\ChattyInterface; class DatabaseUpdatedPrerequisite implements PrerequisiteInterface, ChattyInterface { @@ -234,6 +255,12 @@ this class: Executing the wizard ==================== +.. versionchanged:: 14.0 + While extensions implementing the + :php-short:`\TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface` do not have to + require :composer:`typo3/cms-install` anymore, that extension is still + required to actually run upgrade wizards. + Wizards are listed in the backend module :guilabel:`System > Upgrade` and the card :guilabel:`Upgrade Wizard`. The registered wizard should be shown there, as long as it is not done. diff --git a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php index 9bbd05ec2f..8aa3ab2090 100644 --- a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php +++ b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php @@ -4,8 +4,9 @@ namespace MyVendor\MyExtension\Upgrades; -use TYPO3\CMS\Install\Attribute\UpgradeWizard; -use TYPO3\CMS\Install\Updates\UpgradeWizardInterface; + +use TYPO3\CMS\Core\Attribute\UpgradeWizard; +use TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface; #[UpgradeWizard('myExtension_exampleUpgradeWizard')] final class ExampleUpgradeWizard implements UpgradeWizardInterface diff --git a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_SwitchableControllerActionUpgradeWizard.php b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_SwitchableControllerActionUpgradeWizard.php index 4b3676bec4..e7722d7736 100644 --- a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_SwitchableControllerActionUpgradeWizard.php +++ b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_SwitchableControllerActionUpgradeWizard.php @@ -4,10 +4,10 @@ namespace MyVendor\MyExtension\Upgrades; +use TYPO3\CMS\Core\Attribute\UpgradeWizard; use TYPO3\CMS\Core\Configuration\FlexForm\FlexFormTools; use TYPO3\CMS\Core\Database\ConnectionPool; -use TYPO3\CMS\Install\Attribute\UpgradeWizard; -use TYPO3\CMS\Install\Updates\UpgradeWizardInterface; +use TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface; #[UpgradeWizard('myExtension_switchableControllerActionUpgradeWizard')] final class SwitchableControllerActionUpgradeWizard implements UpgradeWizardInterface From 14b2745c2b41c59fe49442d277cd0dbeb82a47ae Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 1 Dec 2025 06:59:36 +0100 Subject: [PATCH 2/3] [TASK] Allow shipping upgrade wizards w/o requiring EXT:install Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1496 Releases: main --- .../UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php | 1 - 1 file changed, 1 deletion(-) diff --git a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php index 8aa3ab2090..e1b03ef027 100644 --- a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php +++ b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/_ExampleUpgradeWizard.php @@ -4,7 +4,6 @@ namespace MyVendor\MyExtension\Upgrades; - use TYPO3\CMS\Core\Attribute\UpgradeWizard; use TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface; From 488155a86c7150e4264d00eeefdcae8d427a9a11 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Fri, 5 Dec 2025 12:07:20 +0100 Subject: [PATCH 3/3] [FEATURE] Add attribute AsNonSchedulableCommand for "schedulable" Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/1470 Releases: main --- .../HowTo/UpdateExtensions/UpdateWizards/Creation.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst index d46acbddf1..348f187e34 100644 --- a/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst +++ b/Documentation/ExtensionArchitecture/HowTo/UpdateExtensions/UpdateWizards/Creation.rst @@ -120,7 +120,6 @@ command: .. include:: /_includes/CliCacheFlush.rst.txt - .. index:: Upgrade wizards; Identifier .. _upgrade-wizards-identifier: @@ -256,10 +255,11 @@ Executing the wizard ==================== .. versionchanged:: 14.0 - While extensions implementing the - :php-short:`\TYPO3\CMS\Core\Upgrades\UpgradeWizardInterface` do not have to - require :composer:`typo3/cms-install` anymore, that extension is still - required to actually run upgrade wizards. + The upgrade wizards can always be run via the console command + `typo3 upgrade:run`. + + The backend module :guilabel:`System > Upgrade` can only be used if + :composer:`typo3/cms-install` is installed. Wizards are listed in the backend module :guilabel:`System > Upgrade` and the card :guilabel:`Upgrade Wizard`. The registered wizard should be shown