Switchable Controller Actions sind schon seit geraumer Zeit ein Kernkonzept in TYPO3, das es Integratoren und Entwicklern ermöglicht, flexible Verhaltensweisen für ihre Plugins zu definieren. Bei der Aktualisierung oder Umstrukturierung von Erweiterungen, insbesondere bei Projekten, die sich im Laufe der Zeit weiterentwickelt haben, kann es jedoch erforderlich sein, bestehende Flexform-Einstellungen zu migrieren, um sie an neue Listentypen oder geänderte Controller-Aktions definitionen anzupassen.
In diesem Tutorial zeigen wir Ihnen einen einfachen Weg, wie Sie eine solche Migration durchführen können, ohne jeden Datensatz manuell anpassen zu müssen. Am Ende dieses Artikels wissen Sie, wie Sie eine benutzerdefinierte Upgrade-Assistenten-Klasse erstellen und registrieren können, um Ihre vorhandenen Switchable Controller Actions automatisch auf neue Listentypen zu migrieren.
Warum Sie diese Migration brauchen könnten
1. Refactoring oder Umbenennung von Controller-Aktionen
Wenn sich Ihre Erweiterung weiterentwickelt, werden Sie möglicherweise Controller-Aktionen umbenennen oder neu organisieren. Dies kann die Verbindung zwischen den bestehenden flexform switchableControllerActions und Ihren neu umstrukturierten Controllern unterbrechen.
2. Ändern von Plugins / List Types
In TYPO3 definiert der "list_type", welches Plugin von einem Inhaltselement verwendet wird. Wenn Sie ein neues Plugin einführen oder ein bestehendes Plugin umbenennen, müssen Sie sicherstellen, dass alle Referenzen in tt_content korrekt aktualisiert werden.
3. Einfacher Upgrade-Pfad
Anstatt jedes Inhaltselement im Backend manuell zu bearbeiten, sorgt ein benutzerdefiniertes Migrationsskript für einen sauberen und automatisierten Ansatz. Dies reduziert auch menschliche Fehler und bietet einen wiederholbaren Prozess für zukünftige Migrationen.
Überblick über die Schritte
1. Erstellen Sie Ihre Migrationsklasse
Erstellen Sie einen Upgrade-Assistenten, der alle Datensätze in tt_content basierend auf den alten switchableControllerActions-Referenzen findet und aktualisiert.
2. Registrieren Sie Ihren Upgrade-Assistenten
Machen Sie TYPO3 auf Ihre neue Migrationsklasse aufmerksam, indem Sie sie in der Datei ext_localconf.php unter dem Array SC_OPTIONS hinzufügen.
3. Führen Sie den Upgrade-Assistenten
Uber das TYPO3-Installations tool oder den Wartungsbereich aus, starten Sie den Assistenten und schließen Sie die Migration nahtlos ab.
Schritt 1: Erstellen der Migrationsklasse SwitchableControllerActions
Nachstehend finden Sie ein Beispiel für ein Migrationsskript, das Sie an die spezifischen Anforderungen Ihrer Erweiterung anpassen können. Stellen Sie sicher, dass Sie den Namespace und die Konstanten für Ihr spezielles Projekt anpassen. Dieser einfache Ansatz prüft auf Datensätze in tt_content mit passenden switchableControllerActions und aktualisiert deren list_type entsprechend.
<?php
declare(strict_types=1);
use TYPO3\CMS\Core\Utility\GeneralUtility;
use TYPO3\CMS\Core\Database\ConnectionPool;
use TYPO3\CMS\Install\Updates\UpgradeWizardInterface;
final class SwitchableUpgradeWizard implements UpgradeWizardInterface
{
private const MIGRATION_SETTINGS = [
[
'switchableControllerActions' => 'switchableControllerActions type',
'targetListType' => 'new list type',
],
[
'switchableControllerActions' => 'switchableControllerActions type',
'targetListType' => 'new list type',
],
];
/**
* Return the identifier for this wizard
*/
public function getIdentifier(): string
{
return 'myExtension_exampleUpgradeWizard';
}
/**
* Return the speaking name of this wizard
*/
public function getTitle(): string
{
return 'switchableControllerActions migration';
}
/**
* Return the description for this wizard
*/
public function getDescription(): string
{
return 'migration script for switchableControllerActions';
}
/**
* Execute the update
*/
public function executeUpdate(): bool
{
$success = false;
try {
foreach (self::MIGRATION_SETTINGS as $listType) {
$success = $this->getMigrationRecords($listType);
}
} catch (\Throwable $th) {
return false;
}
return $success;
}
/**
* Is an update necessary?
*/
public function updateNecessary(): bool
{
// You could add logic here to check if any records need migration
return true;
}
/**
* Returns an array of class names of prerequisite classes
*/
public function getPrerequisites(): array
{
return [];
}
/**
* Just a placeholder in case you need extra migration logic
*/
public function performMigration(): bool
{
return true;
}
/**
* Updates tt_content records that match the old switchableControllerActions
*/
protected function getMigrationRecords(array $listType): bool
{
$queryBuilder = GeneralUtility::makeInstance(ConnectionPool::class)
->getQueryBuilderForTable('tt_content');
try {
$queryBuilder
->update('tt_content')
->where(
$queryBuilder->expr()->like(
'pi_flexform',
$queryBuilder->createNamedParameter(
'%' . $queryBuilder->escapeLikeWildcards($listType['switchableControllerActions']) . '%'
)
)
)
->set('list_type', $listType['targetListType'])
->executeStatement();
return true;
} catch (\Throwable $th) {
return false;
}
}
}Wichtige Punkte in dieser Klasse
1. getIdentifier(): Muss mit dem Registrierungsschlüssel in ext_localconf.php übereinstimmen.
2. MIGRATION_SETTINGS: Ein Array von Zuordnungen zwischen Ihren alten umschaltbaren Aktionsreferenzen und dem gewünschten neuen list_type.
3. executeUpdate(): Führt eine Schleife durch das Array und verarbeitet jedes Mapping.
4. getMigrationRecords(): Das Herzstück des Skripts, das die tt_content Datensätze aktualisiert, in denen pi_flexform die angegebene Zeichenfolge enthält.
Sie können die Logik in performMigration() oder executeUpdate() erweitern, wenn Sie zusätzliche Aufgaben haben, z. B. das Aktualisieren verschiedener Datenbankfelder oder das Bereinigen zusätzlicher Daten.
Schritt 2: Registrieren Sie Ihren Upgrade-Assistenten in ext_localconf.php
Sobald Sie die Migrationsklasse erstellt haben, müssen Sie sie TYPO3 bekannt machen. Öffnen (oder erstellen) Sie die Datei ext_localconf.php in Ihrer Extension und fügen Sie den folgenden Ausschnitt ein. Stellen Sie sicher, dass der Namensraum (z.B. \Vender\Extension\Upgrades\SwitchableUpgradeWizard ::class) mit dem tatsächlichen Speicherort Ihrer PHP-Klasse übereinstimmt.
$GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS']['ext/install']['update']['myExtension_exampleUpgradeWizard']
= \Vender\Extension\Upgrades\SwitchableUpgradeWizard::class;Diese Registrierung teilt TYPO3 mit, dass es einen neuen Upgrade-Assistenten mit der Bezeichnung myExtension_exampleUpgradeWizard gibt. Wenn Sie zu Install Tool > Upgrade Wizard gehen, sehen Sie diesen Assistenten, der ausgeführt werden kann.
Schritt 3: Ausführen der Migration
1. Zugriff auf das Installationstool (oder den Wartungsbereich):
Loggen Sie sich in Ihr TYPO3 Backend ein und navigieren Sie zum Bereich "Systemwartung" oder "Upgrade", je nach TYPO3-Version.
2. Suchen Sie Ihren Assistenten in der Upgrade-Liste:
Suchen Sie nach dem Titel "switchableControllerActions migration" oder was immer Sie in getTitle() angegeben haben.
3. Führen Sie den Assistenten aus:
Klicken Sie auf die Schaltfläche "Ausführen" (die Benennung kann je nach TYPO3-Version leicht abweichen). Das Skript sucht nach allen tt_content-Datensätzen, die die alten switchableControllerActions Referenzen enthalten, und aktualisiert deren list_type Felder entsprechend.
Überprüfung
Nachdem Sie den Upgrade-Assistenten ausgeführt haben, sollten Sie dies überprüfen:
Ihre flexform-Daten noch intakt sind.
Das neue Plugin oder der neue Listentyp wird im Backend korrekt angezeigt.
Die Frontend-Funktionalität funktioniert weiterhin wie erwartet mit den aktualisierten Controller-Aktionen.
Wenn Sie eine große Website haben, sollten Sie dieses Skript zunächst auf einer Staging- oder Entwicklungsinstanz testen, um sicherzustellen, dass Sie nicht versehentlich Inhalte zerstören.
Schlussfolgerung
Die Migration von umschaltbaren Controller-Aktionen ist eine wichtige Aufgabe, wenn Sie Ihre TYPO3 Extensions umstrukturieren oder umbenennen. Durch die Erstellung eines benutzerdefinierten Upgrade-Assistenten können Sie diesen Prozess effizienter gestalten und einen reibungslosen Übergang von alten Controller-Action-Referenzen zu aktualisierten gewährleisten. So sparen Sie nicht nur Zeit, sondern halten Ihr System auch sauber und konsistent.
Es steht Ihnen frei, die obigen Schnipsel an die Namespace- und Klassenstrukturen Ihrer eigenen Extension anzupassen. Sobald Sie den Dreh raus haben, werden Sie feststellen, wie leistungsfähig und flexibel TYPO3 Upgrade Assistenten für alle Arten von Migrationen sein können.
Haben Sie Fragen oder Vorschläge, wie Sie die Migration von Switchable Controller Actions weiter vereinfachen können? Wenden Sie sich an uns bei T3Planet - wir freuen uns immer über Tipps, Tricks und Best Practices zu TYPO3!
Happy Upgrading & Happy TYPO3!
Post a Comment