Faragiri

Plugins schreiben lernen WordPress

Die Prioritätsreihenfolge an einer echten Installation gemessen, die Callbacks, die schon auf the_content liegen, und das Return, das ein Wert nie auslassen darf.

4Abschnitte
3Min. Lesezeit
5Tiefe

Ein Wert, drei Besitzer

Wer den Inhalt ändert, und in welcher Reihenfolge

Keine der drei Parteien weiß von den anderen, und was der Leser am Ende sieht, entscheidet allein eine Zahl, die jede für sich gewählt hat.

  • der Kern gibt den Wert bei do_blocks, wpautop und do_shortcode weiter
  • das andere Plugin und der eigene Callback bekommen jeweils, was vorher lief
  • der eigene Callback gibt den Wert zurück, den der Kern benutzt, oder null, wenn er es vergisst
  • WordPress-Kern
  • Ein anderes Plugin
  • Der eigene Callback
  • WordPress-KernFünfzehn Callbacks auf the_content, von Priorität 9 bis 20
  • Ein anderes PluginAngemeldet bei einer Priorität, die aus der eigenen Datei nicht sichtbar ist
  • Der eigene CallbackLäuft vor oder nach beiden, allein entschieden durch seine Zahl

Die markierte Seite ist die, die man aus einem einzelnen Plugin heraus nicht sehen kann. Query Monitor zeigt sie an, und das ist der einzige Weg zu wissen, ob der eigene Callback vor oder nach wpautop läuft.

Ein Filter reicht einen Wert durch die eigene Funktion und nimmt zurück, was sie zurückgibt. Matthias Kern betreibt in Paderborn ein Möbelhaus und hat auf seiner WordPress-7.1-Installation zwei Filter auf denselben Wert gesetzt: einer verdoppelt bei Priorität 10, ein zweiter addiert 9 bei Priorität 20. Mit 60 als Eingabe kommt 129 heraus. Die niedrigere Priorität läuft zuerst, und der zweite Filter bekommt die Ausgabe des ersten.

Jetzt der Fehler, der die meisten WordPress-Supportanfragen erzeugt. Ein Filter-Callback, der den Wert ändert und das Zurückgeben vergisst, lässt apply_filters NULL antworten. Nicht den ursprünglichen Wert, keinen Fehler: null, weitergereicht an das, was der Kern damit vorhatte. Jeder Filter-Callback endet mit einem Return, ohne Ausnahme.

Actions und Filter sind dieselbe Maschine, anders benutzt

  • Eine Action ist ein Zeitpunkt: etwas ist passiert, mach, was du willst, nichts wird zurückerwartet
  • Ein Filter ist ein Wert auf der Durchreise: ändere ihn oder nicht, und gib ihn in jedem Fall zurück
  • Beide laufen in Prioritätsreihenfolge, niedrige Zahlen zuerst, und beide rufen jeden angemeldeten Callback auf
  • Das vierte Argument von add_filter sagt, wie viele Argumente der eigene Callback erwartet, und es beim Standardwert 1 zu belassen, während die Funktion zwei Parameter deklariert, ist ein fataler Fehler in dem Moment, in dem der Hook feuert

Der letzte Punkt ist es wert, genannt zu werden, weil der Fehler an einer unerwarteten Stelle auftaucht: Der Hook feuert tief im Kern, also nennt die Meldung eine Datei, die Kern nie geöffnet hat, und die Ursache ist eine fehlende Zahl im eigenen Plugin.

Wie voll ein Hook schon ist

Kerns Installation hat 733 Hooks registriert, sobald eine Seite fertig ist, und allein the_content trägt 15 Callbacks. Sie in der Reihenfolge zu lesen erklärt Verhalten, das sonst wie Zauberei wirkt: do_blocks bei Priorität 9 rendert die Blockmarkierung, wptexturize und wpautop bei 10 erledigen Typografie und Absätze, do_shortcode bei 11, und ein Bildattribut-Filter bei 12 ergänzt die Bildattribute.

Deshalb ist die Priorität eine echte Entscheidung und kein Standardwert. Ein Callback bei 9 sieht rohe Blockmarkierung, derselbe Callback bei 20 sieht fertig gerendertes HTML mit bereits erweiterten Absätzen und Shortcodes. Die falsche Seite von wpautop zu wählen ist der Grund, warum ein eingefügtes Element in einem überflüssigen Absatz-Tag landet.

Was 2026 beim Debuggen hilft

Query Monitor ist das Werkzeug, kostenlos und quelloffen, und das eine Plugin, das auf jeder Entwicklungsinstallation lohnt. Es listet die Hooks, die für die aktuelle Anfrage feuerten, mit ihren Callbacks, die Datenbankabfragen mit ihren Aufrufern, und die PHP-Hinweise, was das alles vom Lesen zum Hinsehen macht. Es hat error_log-Aufrufe in Kerndateien abgelöst.

WP_DEBUG mit WP_DEBUG_LOG ist das zweite, kostenlos mit WordPress, und auf jeder Installation standardmäßig aus. Damit eingeschaltet erscheint das fehlende Return oben als Hinweis in wp-content/debug.log statt als leere Fläche auf der Seite. Es hat das Entwickeln mit versteckten Fehlern ersetzt, dem Standard und dem Grund, warum solche Fehler so lange überleben.

Wo ein Hook verloren geht

Der Stall ist, den Kern oder die Dateien des übergeordneten Themes zu bearbeiten, weil ein Hook nicht zu finden war. Die Änderung wirkt, überlebt bis zur nächsten Aktualisierung und ist dann spurlos weg, samt dem nie gefundenen Hook. Jede solche Bearbeitung ist ein Hook, den jemand nicht gefunden hat, und es gibt mehr davon, als man denkt: 733 auf dieser Installation, vor dem ersten eigenen Plugin.

Die Suche, die einen findet, dauert eine Minute: grep -rn "apply_filters\|do_action" wp-includes/, gefolgt von einer Suche nach dem gesuchten Begriff. Die Hooknamen sind sprechend, sie stehen im Quelltext, und dieses Grep ist schneller als jede Dokumentation. Welche Vorlage einen solchen Hook überhaupt aufruft, klärt Themes, und welche Grundlagen der Sprache dahinterstehen, steht bei PHP-Grundlagen.

Daneben

Darüber