Upgrade-Schritte für Erweiterungen
Diese Anleitung zeigt Entwicklern einer Erweiterung, wie das eigene Upgrade einer Erweiterung, etwa eine neue
Tabelle, eine neue Spalte, eine Standardzeile oder eine Richtlinie, Teil von ./console exp:upgrade wird. Ist der
Schritt registriert, sieht ein Administrator ihn beim Upgrade in exp:upgrade:status, erhält ihn mit
exp:upgrade --apply und hat ihn aufgezeichnet, genauso wie die Schritte des Kernels.
Anleitungen · Siehe auch: Upgrade mit der Konsole, Erweiterungen, Migrationen, Migrationen: der Einstieg, Upgrade-Schritt oder Migration?, Migrationen in einer Erweiterung oder einem Paket
Ein Upgrade-Schritt oder eine Migration? Ein Upgrade-Schritt ist für das, was jede Installation der Erweiterung
beim Upgrade braucht: Er kann die Installation befragen (detect()) und wird von exp:upgrade mit den Schritten des
Kernels ausgeführt. Eine Migration in extension/<name>/migrations/ ist eine Änderung, die einmal geschrieben und
der Reihe nach mit den eigenen Migrationen einer Site angewendet wird (exp:migration:migrate), mit einem
Sicherungspunkt davor und einer Aufzeichnung des Laufs; nehmen Sie sie für Änderungen, auf denen eine Site aufbaut und
die ihre eigenen Migrationen in requires: nennen können. Beide werden in derselben Tabelle exp_migration
aufgezeichnet und laufen unter derselben Sperre (PHP-Migrationen).
Der Schritt
Ein Schritt ist eine Klasse, die expUpgradeStep implementiert (kernel/classes/upgrade/expupgradestep.php). Drei
Basisklassen erledigen den größten Teil:
| Basisklasse | Für | Sie schreiben |
|---|---|---|
expUpgradeSchemaStep | Tabellen, Spalten und Indizes aus einem .dba-Schema | tables(), fields(), indexes() |
expUpgradeScriptStep | alles andere: Zeilen, Richtlinien, Einstellungen, Dateien | changes() (was fehlt, je eine Zeile) und write() |
expUpgradeBaseStep | die Vorgaben (jede Engine, keine Abhängigkeit, Version 6.0.15) | alles Übrige |
Jeder Schritt hat:
id(): dauerhaft gleich,<Version>-<Name>, zum Beispiel1.4.0-myext-widget-table. Sie ist das, was die Aufzeichnung behält und was Administratoren an--onlyund--skipübergeben. Benennen Sie sie nie um.stage():databaseoderscripts(finishgehört dem Kernel).version(): das Release der Erweiterung, das ihn gebracht hat. Schritte laufen nach Stufe, dann nach Version, dann in der aufgelisteten Reihenfolge.engines():array( '*' )oder die Engines, für die er gilt (mysql,postgresql,sqlite,oracle,mongodb).after(): Schritt-IDs, die vorher erledigt sein müssen.detect( $context ): was die Installation jetzt enthält:PRESENT,MISSING,NOT_APPLICABLEoderUNKNOWN, mit einem Detail. Sehen Sie in der Installation selbst nach (im Katalog der Datenbank, in der Rolle, in den Einstellungen), nie nur in der Aufzeichnung: Ein Administrator kann den Schritt von Hand erledigt haben.plan( $context ): wasapply()ändern würde, je eine Zeile, für den Probelauf. Er darf nichts ändern.apply( $context ): nimmt die Änderung vor und gibt zurück, was er getan hat; im Fehlerfall wirft er eine Ausnahme. Er muss wiederholbar sein und einen halb ausgeführten Zustand vervollständigen:exp:upgradekann ihn nach einem Fehler erneut ausführen.
Verwenden Sie $context->db() für die Datenbank, nie ein eigenes eZDB::instance(): Tests führen Schritte auf
anderen Verbindungen aus.
Eine Tabelle und eine Spalte
Eine neue Tabelle braucht keinen eigenen Schritt: der Kernel-Schritt 6.0.15-active-extension-tables legt die
fehlenden Tabellen der share/db_schema.dba jeder aktiven Erweiterung an, und eine neue Installation tut dasselbe nach
ihrem Site-Paket (woher die Tabellen
kommen). Schreiben Sie einen
Schritt für das, was er nicht tut: eine Spalte oder einen Index einer bestehenden Tabelle, Zeilen, Richtlinien,
Einstellungen.
Die Erweiterung hält ihre Tabellen in share/db_schema.dba, wie der Kernel. Der Schema-Schritt liest die
Definitionen aus der Datei, die Sie nennen, legt fehlende Tabellen über die Schema-Klasse der Engine an und ergänzt
fehlende Spalten und Indizes:
class myextUpgradeStepWidgetTable extends expUpgradeSchemaStep
{
public function id() { return '1.4.0-myext-widget-table'; }
public function version() { return '1.4.0'; }
public function description() { return 'myext: the widget table and its owner column'; }
public function tables() { return array( 'myext_widget' ); }
public function fields() { return array( 'myext_item' => array( 'owner_id' ) ); }
public function indexes() { return array( 'myext_item' => array( 'myext_item_owner' ) ); }
}Der Kontext liest standardmäßig das Kernel-Schema. Für das eigene .dba der Erweiterung geben Sie dem Schritt einen
Kontext mit dieser Datei:
public function detect( expUpgradeContext $context ) { return parent::detect( $this->own( $context ) ); }
public function plan( expUpgradeContext $context ) { return parent::plan( $this->own( $context ) ); }
public function apply( expUpgradeContext $context ) { return parent::apply( $this->own( $context ) ); }
private function own( expUpgradeContext $context )
{
return new expUpgradeContext( $context->db(), $context->isApply(), array(), 'extension/myext/share/db_schema.dba' );
}Zeilen, Richtlinien und Einstellungen
class myextUpgradeStepDefaultCategory extends expUpgradeScriptStep
{
public function id() { return '1.4.0-myext-default-category'; }
public function version() { return '1.4.0'; }
public function description() { return 'myext: the category "General" exists'; }
public function after() { return array( '1.4.0-myext-widget-table' ); }
protected function changes( expUpgradeContext $context )
{
$rows = $context->db()->arrayQuery( "SELECT id FROM myext_category WHERE identifier = 'general'" );
return $rows ? array() : array( 'create the category "General"' );
}
protected function write( expUpgradeContext $context )
{
$context->db()->query( "INSERT INTO myext_category ( identifier, name ) VALUES ( 'general', 'General' )" );
return array( 'created the category "General"' );
}
}expUpgradeScriptStep macht aus changes() den Zustand (eine leere Liste heißt vorhanden), verwendet sie als
Probelauf und fragt nach write() erneut changes(): Was dann noch aufgelistet wird, lässt den Schritt scheitern.
Setzen Sie $this->notApplicable = true mit einem $this->reason, wenn der Schritt nicht gilt (die Funktion ist
abgeschaltet), oder geben Sie null mit einem Grund zurück, wenn es sich nicht feststellen lässt.
Hat die Erweiterung schon einen Setup-Befehl, rufen Sie die Klasse auf, die dieser Befehl verwendet, mit den
Standardoptionen des Befehls, so wie es die Richtlinien-Schritte des Kernels tun
(kernel/classes/upgrade/steps/expupgradestepeditorpolicies.php). Starten Sie in einem Schritt nicht das Skript des
Befehls.
Die Schritte registrieren
In der settings/upgrade.ini.append.php der Erweiterung:
[UpgradeSettings]
ExtensionStepList[]=myextUpgradeStepWidgetTable
ExtensionStepList[]=myextUpgradeStepDefaultCategoryErzeugen Sie die Autoloads (php bin/php/ezpgenerateautoloads.php -e) und prüfen Sie:
./console exp:upgrade:steps --stage=database
./console exp:upgrade:statusEine Klasse, die nicht im Autoload-Array steht oder expUpgradeStep nicht implementiert, wird als Warnung gelistet
und weggelassen; zwei Schritte mit derselben ID, ein after(), das keinen Schritt nennt, und ein Zyklus sind
ebenfalls Warnungen.
Liefern Sie die Schritte im Repository der Erweiterung und in ihrem -ezpackage-Repository gleichermaßen aus: Beide
werden installiert, und beide werden aktualisiert.
Die Schritte einer Erweiterung sind ebenfalls Migrationen der Quelle kernel, wie die des Kernels
(Die Schritte unter den Migrationen):
./console exp:migration:status und Setup > Migrationen listen sie, und ./console exp:migration:migrate --apply
führt die ausstehenden der Stufen database und scripts vor den Migrationen aus. Eine Migration in
extension/<name>/migrations/, die die Tabelle des Schritts braucht, nennt ihn in ihrem Kopf
(requires: myext-1.2-widget-table). Wählen Sie einen Upgrade-Schritt für das, was jede Installation der Erweiterung
beim Upgrade braucht, und eine Migration für eine Änderung, die eine Site einmal vornimmt.
Einen Schritt testen
Testen Sie jeden Schritt auf vier Arten auf einer Wegwerf-Datenbank (immer SQLite; MySQL und PostgreSQL, wo möglich):
- eine neue Installation:
not-needed; - Schema und Daten des vorigen Releases:
pending, dannexp:upgrade --apply, danndone; - ein zweites
--apply: nichts ändert sich; - halb ausgeführt (eine von zwei Tabellen, eine von zwei Spalten): der Lauf vervollständigt es.
expUpgrade::run( array( 'database', 'scripts' ), array( 'db' => $db, 'apply' => true ) ) führt die Stufen auf einer
Verbindung Ihres Tests aus. Die Tests des Kernels liegen in tests/tests/kernel/classes/upgrade/.