Fallstudie: von eZChangeclass zu expchangeclass #

Teil 4, Kapitel 23. Dieses Kapitel verfolgt ein Upgrade von Anfang bis Ende anhand der Historie von se7enxweb/expchangeclass auf GitHub. Es zeigt, in welcher Reihenfolge die Arbeit erledigt wurde, warum, und wie jeder Schritt zu einem Release wurde. Jede Aussage hier stammt aus den Commits der Erweiterung, ihrer README oder ihrem Changelog.

Was die Erweiterung tut #

Sie ändert die Inhaltsklasse eines bestehenden Inhaltsobjekts und ordnet jedes Attribut der alten Klasse einem der neuen zu: für ein Objekt aus der Administration (ein Eintrag im Kontextmenü) oder für jedes Objekt einer Klasse über die Kommandozeile.

Woher sie kam #

Die ursprüngliche Erweiterung, eZChangeclass, stammt aus dem Jahr 2007 (ihre Copyright-Zeile in ezinfo.php) und steht unter der GPL. Die README von expchangeclass erklärt, dass zwei Forks davon im Umlauf waren und dass keiner davon sicher auszuführen war:

• Ein Fork behielt „die ursprüngliche PHP-4-Form“: eine Klasse conversionFunctions mit einem Konstruktor conversionFunctions() und nicht statischen Methoden, die das Modul statisch aufrief. Unter PHP 8 „bricht er an der Zeile ab, die die Arbeit macht“, mit Non-static method conversionFunctions::customConverter() cannot be called statically.
• Der andere Fork hat das behoben, aber „eine Umwandlung, die mittendrin fehlschlug, wurde nie zurückgerollt, und das Stapelskript konnte nicht enden, wenn sich ein Objekt nicht umwandeln ließ“.

Die neue Erweiterung „nimmt also den Code von OpenContent als Basis, übernimmt die Vorauswahl der Attribute und die Paketierung aus dem Fork von Netgen und behebt, was keiner von beiden hatte“. Das ist ein gutes Vorbild: Lesen Sie zuerst jede vorhandene Version, nehmen Sie das Beste von jeder und sagen Sie, woher jeder Teil stammt.

Der Zeitablauf #

Beachten Sie den Rhythmus: eine Korrektur, dann eine höhere Version, dann die nächste Korrektur. Jedes Release ist klein genug, um es in einer Zeile zu beschreiben, und eine Website kann jedes davon übernehmen.

Schritt 1: sicher machen, bevor es hübsch wird #

Der erste Commit enthielt bereits die Korrekturen, die für Inhalte wichtig sind. Aus dem Changelog von 1.0.0:

• „Die Umwandlung läuft in einer Transaktion und wird als Einheit zurückgerollt.“
• „die() in der Attributschleife durch Ausnahmen ersetzt, sodass ein Fehler zurückgerollt und gemeldet werden kann, statt die Anfrage mitten im Schreiben zu beenden.“
• „Die Zuordnung der Attribute wird gegen die Data Maps beider Klassen geprüft, bevor etwas geschrieben wird.“
• „Konvertierungsmethoden als statisch deklariert, passend zu der Art, wie sie aufgerufen werden.“
• „Konverter von Relationslisten zu Blöcken auf DOMDocument neu geschrieben, als Ersatz für die entfernte eZXML-API aus PHP 4.“
• „Die Umwandlung von Text in ezxmltext escapet den Wert zuerst; Inhalte mit einem kaufmännischen Und oder einer spitzen Klammer erzeugen kein ungültiges XML mehr.“

Eine Erweiterung, die Inhalte umschreibt, darf sie nie halb geändert zurücklassen. Das kam zuerst, vor jedem Styling.

Die Aufrufkonvention, die die README nach der Änderung zeigt:

$error = null;
if ( !conversionFunctions::convertObject( $objectID, $classID, $mapping, $error ) )
{
    // content is exactly as it was
}

Ein Ergebnis und eine Fehlermeldung statt die(), sodass das Modul zeigen kann, was passiert ist.

Schritt 2: Fehler, die beim Lesen der Einstellungen gefunden wurden #

Das Changelog hält einen Fehler fest, den keine PHP-Version gemeldet hätte: changeclass.ini deklarierte die Gruppe [ezstring] zweimal. In INI-Dateien „wird eine wiederholte Gruppe nicht zusammengeführt: das zweite Vorkommen gewinnt“ (README), daher existierte eine Umwandlung stillschweigend nicht. Die Lösung war eine Gruppe pro Quelldatentyp. Lesen Sie die Einstellungen einer alten Erweiterung so sorgfältig wie ihr PHP.

Schritt 3: Zugriff #

„Das Modul deklarierte keine Funktionen, daher war die einzig mögliche Berechtigung alles oder nichts für das Modul.“ Der Fork hat eine Richtlinienfunktion changeclass/convert hinzugefügt, und Commit b86989f zeigt die Menüeinträge nur Benutzern, die sie besitzen:

{if fetch( 'user', 'has_access_to', hash( 'module', 'changeclass', 'function', 'convert' ) )}

Siehe Richtlinienfunktionen und Zugriff.

Schritt 4: Texte, Namen und Nennung der Urheber #

Commit 9f1e911 hat jeden sichtbaren Text zu einem Übersetzungsstring gemacht. Commit f5dadff hat ihr auf der Seite „Über“ einen lesbaren Namen gegeben. Der ursprüngliche Autor bleibt genannt: in ezinfo.php (ein Includes-Eintrag, der eZChangeclass mit seinem Copyright und seiner Lizenz nennt), in composer.json (authors, mit der Rolle „Original author of eZChangeclass“) und in der README, die das ursprüngliche Repository verlinkt.

Schritt 5: das älteste PHP #

Commit 32196f0 hat die PHP-Bedingung erst auf 8.0 erweitert, nachdem der Code „mit PHPCompatibility für PHP 8.0 geprüft, mit PHP 8.0.30 gelintet und geladen und auf einer vollständigen Installation von PHP 8.0 ausgeliefert“ wurde. Die Version wurde im selben Commit in composer.json, extension.xml und ezinfo.php erhöht.

Schritt 6: der Browser #

Die letzten Schritte betrafen die Content Security Policy:

• e2cd128: Die Ergebniskästen der Umwandlung „mit style=""-Attributen und festen roten und grünen Rahmen“ wurden zur gemeinsamen Komponente a4-notice mit is-ok oder is-bad, die „den Admin-Tokens im hellen und im dunklen Modus folgt“, plus einem kleinen Stylesheet, das über BackendCSSFileList[] geladen wird. Ein Test ohne Datenbank hält die Administrations-Templates frei von Inline-CSS.
• 88b60d9: Die Einträge im Kontextmenü „deklarieren ihr Formular in data-menu-form“, mit einem kleinen Skript für ältere Kernel, und ein zweiter Test hält die Templates frei von Inline-Code.

Unterwegs hat 4958e02 einen Wert escapet, der ohne wash ausgegeben wurde: Ein Upgrade ist ein guter Moment, sich jede Stelle anzusehen, an der ein Template Daten ausgibt.

Was Sie daraus mitnehmen können #

1. Lesen Sie jede vorhandene Version und jeden Fork, bevor Sie beginnen; nennen Sie jeden, von dem Sie etwas übernehmen.
2. Beheben Sie zuerst, was Inhalte beschädigen kann.
3. Veröffentlichen Sie oft, ein Thema pro Release, mit der Version in allen drei Dateien.
4. Fügen Sie für jede Art von Problem einen Test hinzu, wenn Sie es beheben, damit es behoben bleibt.
5. Heben Sie sich die visuelle Arbeit für den Schluss auf, aber erledigen Sie sie: Sie ist das, was Benutzer sehen.

Verwandte Seiten #

• Zurück: Tests und CI für eine aktualisierte Erweiterung
• Weiter: Fallstudie: der Layout-Editor auf jQuery 4
• expchangeclass auf GitHub
• Fallstudie: ein Paket aus einem anderen Projekt mit Nennung der Urheber portieren
• Freie Dokumentation: Diese Seite darf unter der GNU FDL 1.3 frei kopiert, übersetzt und verbessert werden.