Wie migriert man Code von Magento 1 zu Magento 2?

Zweiter fundamentaler Bestandteil neben den Daten bei einem Wechsel von Magento 1 zu Magento 2 ist der Code. Auch hier gibt es von Magento ein offizielles Code-Migrations-Tool.

Dieser Artikel ist Teil der Serie „Migration von Magento 1 auf Magento 2„.

Unterscheidung 3rd-Party-Extensions und eigener Code

Im ersten Schritt muss man jedes vorhandene Modul evaluieren, unabhängig davon ob es sich um eine Eigenentwicklung oder um eine Erweiterung eines Drittherstellers handelt.

Die ersten Schritte sind für beiden Fälle gleich:

• Wird die Funktionalität im neuen Shop benötigt? Wenn nein, dann kann das Modul natürlich entfernt werden (= muss im Magento-2-Shop nicht eingebaut werden).
• Falls man die Funktionalität benötigt, ist abzuklären: wird der Funktions-Umfang der Extension durch den Magento-2-Core abgedeckt? Da in Magento 2 nach und nach neue Features eingebaut werden, ist das nicht auszuschließen.  In diesem Fall sollte die Extension entfernt und stattdessen die Core-Funktionalität verwendet werden, weil das den zukünftigen Wartungs-Aufwand vermindert und die Gefahr von Konflikten mit anderen Extensions vermindert.

Hier enden die Gemeinsamkeiten. Für eine 3rd-Party-Extension ist in nächsten Schritten zu klären:

• Vertraut man weiter diesem Extension-Hersteller? Wenn nein, dann gibt es zwei Möglichkeiten:
  • Man sucht sich eine Extension mit der gleichen Funktionalität bei einem Dritt-Hersteller.
  • Man schreibt die Extension selbst.
• Falls man weiter mit dem Extension-Hersteller arbeiten möchte ist aber noch zu klären, ob es von dem überhaupt in absehbarer Zeit eine Magento-2-Version des Moduls gibt.
  • Falls ja: die Magento-2-Version des Moduls einsetzen. Das sollte auch die Daten-Migration erleichtern.
  • Falls nein: man kann wiederum auf einen anderen Hersteller ausweichen oder die Extension selbst implementieren.

Bei einer eigenen Extension ist es etwas einfacher:

• nun ist der richtige Zeitpunkt zu entscheiden, ob man sich die Eigen-Reimplementierung ersparen und auf eine Dritthersteller-Extension setzen möchte.
  • In zweiterem Fall ist die Sache klar: man sucht die Dritthersteller-Extension.
  • In erstem Fall hat man die Option zwischen zwei Wegen: einem kompletten Rewrite der Extension oder einer Migration.

Kompletter Rewrite der Extension

Den Code der Extension von Grund auf neu zu schreiben, ist sicher der sauberste Weg. Einige Gründe sprechen dafür:

• wenn es sich um eine umfangreiche Extension handelt
• wenn man auf die neuen Framework-Features von Magento setzen möchte
• wenn man das Modul von Anfang an mit automatisierten Tests versehen und entsprechend der neuen Coding-Standards programmieren möchte

Entscheidet man sich für diesen Weg, dann sollte man zuvor das Verhalten der Magento-1-Extension genau dokumentieren damit man verifizieren kann, dass man im Magento-2-Code die gesamte Funktionalität abgedeckt hat und es nicht zu bösen Überraschungen kommt.

Außerdem ist zu überlegen, ob man bei der Gelegenheit nicht etwas mehr Komplexität in Kauf nimmt und möglichst viel Code Plattform-unabhängig gestaltet, das heißt den Code so weit wie möglich von den Spezifika von Magento 2 frei hält. Damit steigen die Chancen, dass man beim Wechsel auf eine weitere Plattform wie z.B. Magento 3 mehr Code wiederverwenden kann als beim letzten Mal.

Migration des Magento-1-Extension-Codes

Die andere Möglichkeit ist, den bestehenden Magento-1-Code zu migrieren. Dieser Weg ist anzudenken, wenn

• das Modul nicht komplex ist
• der Code sehr projektspezifisch ist und wahrscheinlich nicht in anderen Projekten wieder verwendet wird
• es schnell / kurzfristig gehen muss und
• man die Änderungen im Code so gering wie möglich halten will

Um Code-Migration-Tools zu verwenden sollte der Code zuerst entsprechend der Magento-1-Best-Practices „aufgeräumt“ werden. Dazu gehört auch das Entfernen von Core-Overrides. Das vereinfacht die automatische Code-Migration sehr. Zudem ist das der ideale Zeitpunkt, den Code durch weiteres Refactoring sauberer, stabiler und wiederverwendbarer zu gestalten.

Nicht zuletzt sollte auch hier das Magento-1-Verhalten dokumentiert und Plattform-unabhängige Programmierung angestrebt werden.

Was kann das offizielle Code-Migrations-Tool?

Nehmen wir also an, wir wollen Code mit dem offiziellen Code-Migrations-Tool von Magento 1 auf Magento 2 umschreiben.

Was kann das Tool für uns tun?

• Die Klassen-Namen werden in Namespaces umgeschrieben.
• Die Verzeichnisstruktur wird von Magento 1 auf Magento 2 umgebaut.
• Die XML-Konfigurations-Dateien werden aus den wenigen großen Dateien von Magento 1 in die vielen kleinen Files von Magento 2 aufgespalten.
• Auch die umfangreichen Layout-XML-Files aus Magento 1 werden in die granularen Magento-2-Versionen zerlegt
• Das bisherige Magento-1-Model, wonach Klassen über die Mage-Gott-Klasse initialisiert werden wird durch Dependency Injection (DI) ersetzt.

Bei einigen Dingen muss aber selbst Hand angelegt werden:

• das Design muss komplett manuell migriert werden, das heißt der Template-Code sowie das JavaScript und CSS
• Anpassungen an der Core-Business-Logik im eigenen Code müssen ebenfalls manuell umgeschrieben werden

Installation

Wie schon beim Daten-Migrations-Tool gestaltet sich die Installation einfach.

Man klont das Git-Repository:

git clone https://github.com/magento/code-migration

Und führt die Composer-Installation aus:

composer install

Das war es auch schon.

Vorbereitung

Somit ist das Tool einsatzbereit. Was man nun braucht, sind ein paar Verzeichnisse (die Bezeichnungen in den eckigen Klammern sind von mir und können auch anders lauten):

• <src>: enthält den zu migrierenden Code ohne den Core – die Verzeichnis-Struktur ist aber so, wie man sie in Magento 1 kennt
• <m1>: der komplette Magento-1-Projekt-Code inklusive des unveränderten M1-Core
• <m2>: der unveränderte Magento-2-Core
• <dst>: ein leeres Verzeichnis, in das der generierte Magento-2-Code geschrieben wird

Durchführung der Code-Migration

Mit den auf diese Weise vorbereiteten Verzeichnissen kann man sich an die Migration machen. Hierfür verwendet das Tool vier Befehle, die in dieser Reihenfolge ausgeführt werden:

• Migrieren der Verzeichnis-Struktur

  php bin/migrate.php migrateModuleStrucutre <src> <dst>

• Migrieren der Layout-Files

  php bin/migrate.php convertLayout <dst>

• Migrieren der Konfigurations-Dateien

  php bin/migrate.php convertConfig <dst>

• Migrieren des PHP-Codes

  php bin/migrate.php convertPhpCode <dst> <m1> <m2>

Erkenntnisse aus der Praxis

Aus meinen Experimenten mit diesem Tool habe ich ein paar Erfahrungen mit genommen, die ich hier teilen möchte:

Nicht von den Verzeichnissen verwirren lassen. Es ist erstaunlich einfach, bei diesen vier Verzeichnissen durcheinander zu kommen, gerade wenn man diese Schritte mit mehreren Projekten / Modulen wiederholt. Ich habe mich daher auf die oben genannten Namen fest gelegt, die ich immer wieder verwende.

Abläufe automatisieren. Um in der Migration leicht verschiedene Projekte gegen verschiedene Magento-2-Versionen laufen lassen zu können, automatisiere ich so viel wie möglich. Ein einfaches Beispiel: man kann seine Befehle gegen fixe Pfade laufen lassen, die aber nur Symlinks auf die wirklichen Endziele darstellen und so mit dem gleichen Befehl diverse Mutationen laufen lassen:

Nach Möglichkeit von der aktuellen M1-Version auf Magento 2 migrieren. Das Code-Migrations-Tool benötigt so genannte Mapping-Files, um den Magento-1-Code auf Magento 2 umbauen zu können. Von Haus aus liefert das Tool nur Mapping-Files für die aktuelle Version mit. Man kann diese Mapping-Files zwar selbst für beliebige Versionen generieren, aber das hat sich in der Vergangenheit immer wieder einmal als leicht fehleranfällig erwiesen. Daher würde ich nach Möglichkeit auf die mitgelieferten Mapping-Files setzen und lieber vorher die Magento-Version updaten.

Doppelt kontrollieren, was (nicht) konvertiert worden ist. Prinzipiell macht das Magento recht gut: man hat die Original- und die konvertierte Datei vorliegen und kann vergleichen, was wie übertragen worden ist. Allerdings muss man gerade bei den XML-Files darauf achten genau zu kontrollieren, was an Code migriert wurde und was nicht. Es gibt nämlich Teile im XML (und teilweise sind das nur Feinheiten), die still und klamm-heimlich nicht in das neue XML übernommen werden.

Fazit

Man muss seine komplette Code-Basis durchgehen und entscheiden: benötigt man eine Funktionalität noch? Wird sie nun durch den Magento-2-Code abgedeckt? Wenn es sich um eine Third-Party-Extension handelt, soll weiter auf den Hersteller gesetzt werden, soll ein anderer Extension-Hersteller betraut werden oder setzt man das Feature selbst um?

Macht man sich selbst ans Programmieren, dann muss man sich entscheiden ob man die Extension von Grund auf neu schreibt oder migriert. Ersteres macht sich langfristig bezahlt wenn die Extension komplex ist, wieder verwendet werden soll, man die Vorteile von Magento 2 nutzen will und man das Budget (= Zeit und Geld) dazu hat. Die automatische Code-Migration kann hier Basis-Schritte erleichtern oder den Code zu großen Teilen automatisch für Magento 2 umschreiben, wenn es schnell gehen muss und keine großen Ansprüche an die Zukunftsträchtigkeit und Anmut des Codes gestellt wird.