Row updaters: migrate single table rows 

New in version 15.0 Feature: #110269 - Allow row updater registration with PHP attribute

Extensions can register row updaters with the PHP attribute AsRowUpdater .

A row updater migrates data row by row. Use it for a migration that a plain SQL statement cannot express. The upgrade wizard Execute database migrations on single rows (identifier databaseRowsUpdateWizard) runs all registered row updaters:

  • It reads each table with TCA once. All rows are included, also deleted and hidden ones.
  • It passes each row to every row updater that reported a potential update for the table.
  • It writes only the fields that a row updater changed.
  • It stores its position, so an interrupted run continues where it stopped.

Implement a row updater with RowUpdaterInterface 

A row updater implements RowUpdaterInterface and is registered with the attribute AsRowUpdater :

EXT:my_extension/Classes/Upgrades/RowUpdater/EventStatusRowUpdater.php
<?php

declare(strict_types=1);

namespace MyVendor\MyExtension\Upgrades\RowUpdater;

use TYPO3\CMS\Core\Attribute\AsRowUpdater;
use TYPO3\CMS\Core\Upgrades\RowUpdater\RowUpdaterInterface;

#[AsRowUpdater('myExtension_eventStatus')]
final class EventStatusRowUpdater implements RowUpdaterInterface
{
  private const TABLE = 'tx_myextension_domain_model_event';

  public function getTitle(): string
  {
    return 'Migrate the status "archived" of events to "closed"';
  }

  public function hasPotentialUpdateForTable(string $tableName): bool
  {
    return $tableName === self::TABLE;
  }

  public function updateTableRow(string $tableName, array $row): array
  {
    if ($row['status'] === 'archived') {
      $row['status'] = 'closed';
    }
    return $row;
  }
}
Copied!
Method getTitle()
Return the name that the wizard lists for this row updater.
Method hasPotentialUpdateForTable()
Return true if the row updater can change rows of the given table. The wizard passes only the rows of these tables.
Method updateTableRow()
Return the row, changed or unchanged.

Identifier of a row updater 

The attribute takes an identifier as argument. Without it, the fully qualified class name is the identifier. The identifier must be unique across all row updaters. Use the naming convention of the wizard identifier.

The wizard stores the identifier in the table sys_registry after the row updater was executed. Do not change the identifier afterwards, otherwise the row updater runs again.

Register a row updater with the service tag install.rowupdater 

If the class cannot carry the attribute, register it with the service tag install.rowupdater :

EXT:my_extension/Configuration/Services.yaml
services:
  # Place here the default dependency injection configuration

  # Only necessary when the class cannot carry the attribute
  MyVendor\MyExtension\Upgrades\RowUpdater\EventStatusRowUpdater:
    tags:
      - name: install.rowupdater
        identifier: 'myExtension_eventStatus'
Copied!

Execute the row updaters 

The wizard lists the row updaters that were not executed yet, and it is shown as long as one of them is left. Run it in the backend module System > Upgrade or on the command line:

vendor/bin/typo3 upgrade:run databaseRowsUpdateWizard
Copied!
typo3/sysext/core/bin/typo3 upgrade:run databaseRowsUpdateWizard
Copied!

See Executing the wizard.