Upgrades

Wenn sich die Struktur deines Drops durch Änderungen an der config.json ändert, kann es notwendig sein, eine neue Version für dein Drop einzuführen um Daten zu migrieren. Hierdurch bist du in der Lage, bestehende Drop-Instanzen deines Drops in die neue Strutkur zu überführen. Dropper bietet dir hierfür einen Upgrade-Mechanismus an.

Die upgrade.php ist eine PHP-Datei, die für Datenmigrationen deiner Drops zwischen neuen Versionen verantwortlich ist. Eine Migration auf eine neue Drop-Version kann darin von dir definiert werden und du hast die Möglichkeit Code auf den Daten der betroffenen Drops auszuführen:

ACME_Demo/config.json

In der Konfigurationsdatei deines Drops hast du die Möglichkeit eine Versionsnummer deines Drops zu pflegen. Diese solltest du heraufsetzen um ein neues Upgrade anzulegen.

{
    "name": "Demo Drop",
    "description": "Ein kleines Demo Drop",

    "version": "1.0.2",

    ...
}

Für jeden Sprung in der Versionsnummer deines Drops solltest du jetzt eine Upgrade-Funktion anlegen, welche bestehende Daten deiner Drop-Instanzen migriert oder neue Eigenschaften hinzufügt, falls in deiner Konfiguration neue Einstellungen eingeführt wurden. Hierzu erstellst du eine neue Klasse mit der Namenskonvention <DropID>Upgrader welche die Klasse DropUpgrader erweitert. Diese Klasse muss eine Funktion register() implementieren welche vom Dropper Upgrade-Manager aufgerufen wird um deine Upgrades zu registrieren.

ACME_Demo/upgrade.php

class ACME_DemoUpgrader extends DropUpgrader {

    /**
     * Register ACME_Demo upgrades
     */
    function register() {

        $this->addUpgrade(
            '1.0.0', '1.0.1',
            'Adds a new Property "demo" to each drop instance',
            function($drop) {
                $drop['demo'] = true;
                return $drop;
            }
        );

        $this->addUpgrade(
            '1.0.1', '1.0.2',
            'Removes the "demo" property, introduced in version 1.0.1',
            function($drop) {
                $this->unsetProps($drop, ['demo']);
                return $drop;
            }
        );

    }
}

Nach dem erneuten Laden des Dropper Backends werden alle Instanzen deines Drops automatisch in die entsprechenden Upgrade-Funktionen gegeben. Hierbei ist es auch möglich, dass diese mehrere Upgrade-Funktionen nacheinander durchlaufen. In den Upgrade-Funktionen kannst du die Daten der Instanzen modifizieren. Wichtig ist, dass die Upgrade-Funktion die modifizierte Drop-Instanz auch wieder zurückgibt (return $drop;).

Um einen Fehler beim Upgrade zu erzeugen, gebe anstatt der $drop Instanz einen String mit der Fehlernachricht zurück. Diese wird dem Nutzer dann im Dropper Backend angezeigt. Alternativ kannst du eine Exception werfen (manchmal hilfreich beim Debuggen).