Update- und Post-Update-Hooks für erfolgreiche Drupal-Site-Updates verstehen

Während Core-Updates oder Modul-Updates ist es entscheidend, die Stabilität und Integrität Ihrer Drupal-Website zu gewährleisten. Glücklicherweise sind das Update-API-Modul und Update/Post-Update-Hooks hier, um zu helfen.

Das Update-API-Modul stellt die Hooks bereit, die zum Aktualisieren von Code und Modulen auf Ihrer Drupal-Site erforderlich sind. Diese Hooks sind nichts anderes als Update- und Post-Update-Hooks, die es Entwicklern ermöglichen, Updates an ihre Bedürfnisse anzupassen.

In diesem Artikel besprechen wir die Update-API, was Update- und Post-Update-Hooks sind und wann und wie sie verwendet werden sollten. Wenn Sie beide Arten von Hooks verstehen, können Sie Ihre Drupal-Site mit minimalem Aufwand erfolgreich aktualisieren. Lass uns anfangen!

Die Update-API

Während Sie an einer vorhandenen Site arbeiten und Code in einem Modul aktualisieren, müssen Sie möglicherweise gespeicherte Daten aktualisieren, damit die gespeicherten Daten mit dem neuen Code kompatibel sind. Möglicherweise sind Ihnen Fehler wie „Auf der Website ist ein unerwarteter Fehler aufgetreten“ aufgefallen. Gruselig oder!? Ich weiss! Hier kommt uns die Update-API von Drupal zu Hilfe.

Wenn das Update zwischen zwei Nebenversionen Ihres Moduls innerhalb derselben Hauptversion des Drupal-Kerns liegt, können Sie die Update-API verwenden, um die Daten zu aktualisieren. Mit der Update-API können Sie Code bereitstellen, der gespeicherte Daten aktualisiert, wenn Ihr Modul eine Änderung an seinem Datenmodell vornimmt. Die Datenmodelländerung bezieht sich auf jede Änderung, die die gespeicherten Daten auf einer bestehenden Site mit der aktualisierten Codebasis dieser Site inkompatibel macht. Diese Datenmodelländerungen beinhalten:

Aktualisieren des Konfigurationsschemas

• Hinzufügen/Entfernen/Umbenennen eines Konfigurationsschlüssels.
• Ändern des Datentyps des Konfigurationsschlüssels.
• Ändern des erwarteten Standardwerts eines Konfigurationsschlüssels usw.

Aktualisieren des Datenbankschemas

• Hinzufügen/Ändern/Entfernen einer Datenbanktabelle oder eines Felds.
• Verschieben der gespeicherten Daten in ein anderes Feld oder eine andere Tabelle.
• Ändern des Formats gespeicherter Daten usw.

Aktualisieren der Entitäten und Felder

• Hinzufügen eines neuen Basisfelds zu einem vorhandenen Entitätstyp.
• Aktualisieren eines Felds von einem veralteten Typ auf einen neuen Typ usw.

Aktualisieren der Daten

• Manipulieren Sie die gespeicherten Daten auf einer bestehenden Website.

Arbeiten mit Update-Hooks

Hook hook_update_N() wird verwendet, um ein Update zwischen Nebenversionen eines Moduls einzuführen. Diese Hooks werden innerhalb Ihres Moduls in der *.install- Datei platziert.

Hook_update_N() wird in Form von (Modulname)_update_(Nummer) geschrieben. Hier besteht N aus:

• 1 oder 2 Ziffern beziehen sich auf die Drupal-Core-Kompatibilität (Drupal 8, 9, 10 usw.)
• Die nächste Ziffer steht für die Hauptversion Ihres Moduls
• Die letzten 2 Ziffern für fortlaufendes Zählen, beginnend mit 01

Beispiel:

example_update_9201(): Das erste Update für die Versionen 9.x-2.x.
Wo „Beispiel“ der Name des Moduls ist, bezieht sich die erste Ziffer auf die Drupal-Kernversion „9“, die Zahl „2“ bezieht sich auf die Hauptversion des Moduls und die letzten beiden Ziffern „01“ geben die erste Update-Funktion an, für die geschrieben wurde Modul 'Beispiel'.

Der numerische Teil der Hook-Implementierungsfunktion (dh 9201 im obigen Beispiel) wird in der Datenbank gespeichert, um zu verfolgen, welche Aktualisierungen bereits ausgeführt wurden. Daher sollten Sie Aktualisierungsfunktionen niemals neu nummerieren.
Um die aktuelle Schemaversion eines Moduls „Beispiel in Datenbank gespeichert“ zu erfahren, verwenden Sie:

drush php-eval "echo drupal_get_installed_schema_version('example');"

Um die aktuelle Schemaversion eines Moduls „Beispiel“ manuell auf „9201“ zurückzusetzen, verwenden Sie:

drush php-eval "echo drupal_set_installed_schema_version('example', '9201');"

Hinweis: Bitte vermeiden Sie die Verwendung der Funktion drupal_set_installed_schema_version() auf Produktionsseiten, da sie Ihre Datenbank direkt aktualisiert. Sie können es während der Entwicklung in Ihren lokalen oder niedrigeren Testumgebungen verwenden, um die Schemaversion zurückzusetzen.

Fügen Sie eine angemessene Beschreibung im Dokumentblock-Kommentar vor der Update-Hook-Funktion hinzu, da sie für die Benutzer gedruckt wird, während sie ausgeführt wird.

 Structure of hook_update_N(): /** * A aimple hook_update_N() hook. */ function example_update_9201() { // Code goes here. }

Diese Hooks werden in sortierter Reihenfolge ausgeführt, dh der Hook example_update_9201() wird vor example_update_9202() ausgeführt, als nächstes kommt 9203, 9204 und so weiter.

Sie können auch die sortierte Reihenfolge dieser Hooks ändern, indem Sie Abhängigkeiten zwischen den Hooks einführen. Verwenden Sie den Hook hook_update_dependencies(), um Updates zwischen zwei Update-Hooks auszuführen.

Alle Update-Hooks werden stapelweise ausgeführt und unterstützen auch die Stapelverarbeitung von Elementen. Alle Update-Hooks haben Zugriff auf einen $sandbox-Parameter, der verwendet werden kann, um Batch-Prozesse in den Update-Hooks zu erstellen, um große Datenmengen auf einmal zu verarbeiten, ohne dass PHP eine Zeitüberschreitung verursacht.

Ein einfaches Beispiel für einen Update-Hook zum Hinzufügen eines neuen Konfigurationsschlüssels:

Derzeit enthält die Datei example_module.settings.yml Folgendes:

So fügen Sie der Konfiguration eine neue Schlüssel-'Beschreibung' hinzu:

• Fügen Sie der Einstellungsdatei den Schlüssel „Beschreibung“ hinzu

• Fügen Sie den update_hook in der Datei example_module.install hinzu:

• Verwenden Sie drush updb, um den Hook auszuführen.

• Überprüfen Sie die aktualisierte Konfiguration, der neue Schlüssel „Beschreibung“ wird aktualisiert.

Arbeiten mit Post-Update-Hooks

Der Hook hook_post_update_NAME() wird ähnlich wie der Update-Hook verwendet, um ein Update einzuleiten. Aber dieser Hook ist hauptsächlich dazu gedacht, Daten wie Entitäten zu aktualisieren. Diese Hooks werden ausgeführt , nachdem alle hook_update_N()-Hooks ausgeführt wurden. Zu diesem Zeitpunkt ist Drupal bereits vollständig repariert, sodass Sie jede API innerhalb der Website verwenden können.

Diese Hooks werden in einer *.post_update.php-Datei in Ihrem Modul platziert.

Hook_post_update_NAME() wird in der Form (Modulname)_post_update_(beliebiger Name) geschrieben. Dabei kann NAME ein beliebiger Maschinenname sein. Diese alphanumerische Benennung von Funktionen in der Datei ist das einzige, was die Ausführungsreihenfolge dieses Hooks sicherstellt.

Ähnlich wie bei Update-Hooks fügen Sie eine angemessene Beschreibung im docblock-Kommentar vor dem post_update-Hook hinzu. Verwenden Sie außerdem nicht denselben Hook-Namen erneut.

Aufbau von hook_post_update_NAME():

 /** * A aimple hook_post_update_NAME() hook. */ function example_post_update_test() { // Code goes here. }

Verwenden Sie wie bei Update-Hooks den $sandbox-Parameter, um anzugeben, dass die Batch-API für Ihre post_update-Hooks verwendet werden soll.

Ein einfaches Beispiel für die Verwendung des Post-Update-Hooks zum Aktualisieren der Begriffsdaten:

• Derzeit ist für alle Begriffe unter „Tags-Vokabular“ das Feld „Testbeispiel“ deaktiviert.

• Fügen Sie einen post_update-Hook in der Datei example_module.post_update.php hinzu, um das Feld „Testbeispiel“ für alle vorhandenen Begriffe zu aktivieren.

• Verwenden Sie drush updb, um den Hook auszuführen.

• Überprüfen Sie die aktualisierten Termdaten, das Kontrollkästchen „Testbeispiel“ muss aktiviert sein.

Wie man diese Hooks ausführt!

Sie können den Drush-Befehl verwenden, um diese Hooks auszuführen, drush updb. Er erstellt den Stapel in den folgenden Schritten:

• Alle Update-Hooks werden entdeckt.
• Löst Abhängigkeit auf und sortiert ihre Reihenfolge.
• Für die Stapelverarbeitung werden Haken gesetzt.
• Als nächstes werden alle Post-Hooks entdeckt.
• Wenn post_update-Hooks vorhanden sind und update_hook zuvor ausgeführt wurde, werden Caches gelöscht.
• Pushen Sie dann jeden post_update-Hook in den Batch.
• Führen Sie den Stapel aus.

Ein großer Vorteil des Post-Update-Hooks gegenüber dem Update-Hook ist, dass Drupal zum Zeitpunkt der Ausführung des Post-Updates voll funktionsfähig ist. Dadurch können Entwickler alle Drupal-Dienste verwenden, während sie den Post-Update-Hook verwenden. Mit dem Update-Hook darf man nicht davon ausgehen, dass Drupal vollständig repariert ist, und es vermeiden, andere Hooks, Entity-APIs usw. aufzurufen.

Abschließende Gedanken

Wenn Sie versuchen, Ihre Site durch Aktualisieren des Konfigurations-/Datenbankschemas zu reparieren, versuchen Sie, Update-Hooks zu verwenden. Wenn es darum geht, gespeicherte Daten zu manipulieren, Konfigurationen neu zu speichern, Inhaltsentitäten zu aktualisieren, den Cache zu löschen usw., dann sind Post-Update-Hooks besser geeignet.

Um ehrlich zu sein, gibt es auf Drupal.org keine klare Dokumentation darüber, wann welcher Hook verwendet werden soll! Es gibt ein offenes Problem mit der Bitte, die Dokumentation zur Verwendung dieser beiden Hooks zu verbessern, zu der Sie beitragen können, wenn Sie möchten.

Aber basierend auf der Erfahrung der Entwickler und anhand der Kernmodule von Drupal 9 und 10 als Beispiel, verwenden Sie Update-Hooks, um CRUD-Vorgänge an Konfigurationen oder Datenbanken durchzuführen (dh die Site zu reparieren) und verwenden Sie Post-Update-Hooks für CRUD-Inhaltsentitäten ( Korrigieren Sie dann die Daten auf der aktualisierten Site), da Post-Update-Hooks nach Update-Hooks ausgeführt werden.

Haben Sie diesen Artikel gerne gelesen? Zeigen Sie uns etwas Liebe und abonnieren Sie noch heute unseren wöchentlichen Newsletter!