Creating upgrade wizards

UpgradeWizardInterface

Each upgrade wizard consists of a single PHP file containing a single PHP class. This class has to implement \TYPO3\CMS\Install\Updates\UpgradeWizardInterface and its methods.

The registration of an upgrade wizard is done directly in the class by adding the class attribute \TYPO3\CMS\Install\Attribute\UpgradeWizard . The unique identifier is passed as an argument.

<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Upgrades;

use TYPO3\CMS\Install\Attribute\UpgradeWizard;
use TYPO3\CMS\Install\Updates\UpgradeWizardInterface;

#[UpgradeWizard('myExtension_exampleUpgradeWizard')]
final class ExampleUpgradeWizard implements UpgradeWizardInterface
{
    /**
     * Return the speaking name of this wizard
     */
    public function getTitle(): string
    {
        return 'Title of this updater';
    }

    /**
     * Return the description for this wizard
     */
    public function getDescription(): string
    {
        return 'Description of this updater';
    }

    /**
     * Execute the update
     *
     * Called when a wizard reports that an update is necessary
     *
     * The boolean indicates whether the update was successful
     */
    public function executeUpdate(): bool
    {
        // Add your logic here
    }

    /**
     * Is an update necessary?
     *
     * Is used to determine whether a wizard needs to be run.
     * Check if data for migration exists.
     *
     * @return bool Whether an update is required (TRUE) or not (FALSE)
     */
    public function updateNecessary(): bool
    {
        // Add your logic here
    }

    /**
     * Returns an array of class names of prerequisite classes
     *
     * This way a wizard can define dependencies like "database up-to-date" or
     * "reference index updated"
     *
     * @return string[]
     */
    public function getPrerequisites(): array
    {
        // Add your logic here
    }
}

Method getTitle()

Return the speaking name of this wizard.

Method getDescription()

Return the description for this wizard.

Method executeUpdate()

Is called, if the user triggers the wizard. This method should contain, or call, the code that is needed to execute the upgrade. Return a boolean indicating whether the update was successful.

Method updateNecessary()

Is called to check whether the upgrade wizard has to run. Return true, if an upgrade is necessary, false if not. If false is returned, the upgrade wizard will not be displayed in the list of available wizards.

Method getPrerequisites()

Returns an array of class names of prerequisite classes. This way, a wizard can define dependencies before it can be performed. Currently, the following prerequisites exist:

• DatabaseUpdatedPrerequisite: Ensures that the database table fields are up-to-date.
• ReferenceIndexUpdatedPrerequisite: The reference index needs to be up-to-date.

EXT:my_extension/Classes/Upgrades/ExampleUpgradeWizard.php

use TYPO3\CMS\Install\Updates\DatabaseUpdatedPrerequisite;
use TYPO3\CMS\Install\Updates\ReferenceIndexUpdatedPrerequisite;

/**
 * @return string[]
 */
public function getPrerequisites(): array
{
    return [
        DatabaseUpdatedPrerequisite::class,
        ReferenceIndexUpdatedPrerequisite::class,
    ];
}

Copied!

services:
  # Place here the default dependency injection configuration

  # Only necessary when "autoconfigure" is set to false!
  MyVendor\MyExtension\Upgrades\ExampleUpgradeWizard:
    tags:
      - name: install.upgradewizard

After creating the new upgrade wizard, delete all caches in Admin tools > Maintanance > Flush TYPO3 and PHP Cache or via console command:

vendor/bin/typo3 cache:flush

typo3/sysext/core/bin/typo3 cache:flush

Wizard identifier

The wizard identifier is used:

• when calling the wizard from the command line.
• when marking the wizard as done in the table sys_registry

Since all upgrade wizards of TYPO3 Core and extensions are registered using the identifier, it is recommended to prepend the wizard identifier with a prefix based on the extension key.

You should use the following naming convention for the identifier:

myExtension_wizardName, for example bootstrapPackage_addNewDefaultTypes

• The extension key and wizard name in lowerCamelCase, separated by underscore
• The existing underscores in extension keys are replaced by capitalizing the following letter

Some examples:

Marking wizard as done

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 EXT:install/Classes/Updates/RepeatableInterface.php (GitHub) has to be implemented. This interface works as a marker and does not force any methods to be implemented.

Generating output

The ChattyInterface can be implemented for wizards which should generate output. EXT:install/Classes/Updates/ChattyInterface.php (GitHub) uses the Symfony interface OutputInterface.

Classes using this interface must implement the following method:

/**
 * Setter injection for output into upgrade wizards
 */
 public function setOutput(OutputInterface $output): void;

The class EXT:install/Classes/Updates/DatabaseUpdatedPrerequisite.php (GitHub) implements this interface. We are showing a simplified example here, based on this class:

use Symfony\Component\Console\Output\OutputInterface;

class DatabaseUpdatedPrerequisite implements PrerequisiteInterface, ChattyInterface
{
    /**
     * @var OutputInterface
     */
    protected $output;

    public function setOutput(OutputInterface $output): void
    {
        $this->output = $output;
    }

    public function ensure(): bool
    {
        $adds = $this->upgradeWizardsService->getBlockingDatabaseAdds();
        $result = null;
        if (count($adds) > 0) {
            $this->output->writeln('Performing ' . count($adds) . ' database operations.');
            $result = $this->upgradeWizardsService->addMissingTablesAndFields();
        }
        return $result === null;
    }

    // ... more logic
}

Executing the wizard

Wizards are listed in the backend module Admin Tools > Upgrade and the card Upgrade Wizard. The registered wizard should be shown there, as long as it is not done.

It is also possible to execute the wizard from the command line:

vendor/bin/typo3 upgrade:run myExtension_exampleUpgradeWizard

typo3/sysext/core/bin/typo3 upgrade:run myExtension_exampleUpgradeWizard

vendor/bin/typo3 upgrade:run '\\MyVendor\\MyExtension\\Upgrade\\ExampleUpgradeWizard'

typo3/sysext/core/bin/typo3 '\\MyVendor\\MyExtension\\Upgrade\\ExampleUpgradeWizard'