Hooks: Actions und Filter

Jedes Plugin, jedes Theme und große Teile von WordPress selbst funktionieren nach demselben Prinzip: An festgelegten Stellen im Ablauf ruft WordPress „Haken“ auf, an die sich eigener Code hängen kann. So lässt sich das Verhalten der Software verändern, ohne eine einzige Datei des Kerns anzufassen – und genau deshalb überstehen Plugins Updates. Wer Hooks verstanden hat, versteht WordPress. In dieser Lektion lernen Sie die beiden Arten von Hooks kennen, erfahren, wie Prioritäten die Reihenfolge steuern, und bauen am Ende eigene Hooks, mit denen andere Ihren Code erweitern können.

1. Zwei Arten von Hooks

Mit add_action hängt man eine Funktion an eine Action, mit add_filter an einen Filter. Der wichtigste Unterschied: Eine Filterfunktion muss immer einen Wert zurückgeben. Vergisst man das return, verschwindet der Inhalt – einer der häufigsten Anfängerfehler. Klicken Sie sich durch einen typischen Seitenaufruf:

1<?php
2// Action: zusätzlich etwas tun
3add_action( 'init', function () {
4    register_post_type( 'termin', [ 'public' => true, 'label' => 'Termine' ] );
5} );
6
7// Filter: einen Wert verändern – und zurückgeben!
8add_filter( 'the_title', function ( $titel, $id ) {
9    if ( get_post_meta( $id, 'ausgebucht', true ) ) {
10        $titel .= ' (ausgebucht)';
11    }
12    return $titel;
13}, 10, 2 );

2. Priorität und Argumente

Hängen mehrere Funktionen am selben Hook, entscheidet die Priorität über die Reihenfolge. Sie ist der dritte Parameter und beträgt standardmäßig 10; kleinere Zahlen laufen früher. Der vierte Parameter legt fest, wie viele Argumente die Funktion erhält – bei the_title etwa neben dem Titel auch die Beitrags-ID. Bei Filtern wird das Ergebnis jeder Funktion an die nächste weitergereicht. Das Labor zeigt, warum die Reihenfolge wichtig ist:

1<?php
2add_filter( 'the_title', fn( $t ) => $t . ' A', 20 );
3add_filter( 'the_title', fn( $t ) => $t . ' B' );
4add_filter( 'the_title', fn( $t ) => $t . ' C', 5 );
5
6echo apply_filters( 'the_title', 'Kurs' );

3. Hooks entfernen und eigene anbieten

Mit remove_action und remove_filter lässt sich fremder Code wieder abhängen – etwa wenn ein Theme etwas ausgibt, das nicht gewünscht ist. Das funktioniert nur, wenn man Hook, Funktion und Priorität genau kennt; anonyme Funktionen lassen sich deshalb kaum entfernen. Wer selbst ein Plugin schreibt, sollte daher benannte Funktionen oder Methoden verwenden und an wichtigen Stellen eigene Hooks anbieten. Mit do_action und apply_filters entstehen Erweiterungspunkte, die andere nutzen können, ohne Ihren Code zu ändern.

1<?php
2function radwerk_termin_buchen( int $termin_id, array $daten ): bool {
3    // Anderen Plugins erlauben, die Daten vorab anzupassen
4    $daten = apply_filters( 'radwerk_buchungsdaten', $daten, $termin_id );
5
6    $ok = radwerk_speichern( $termin_id, $daten );
7
8    if ( $ok ) {
9        // Anderen Plugins mitteilen: Es wurde gebucht
10        do_action( 'radwerk_termin_gebucht', $termin_id, $daten );
11    }
12    return $ok;
13}

4. Ein Beispiel

Ein Fahrradladen nutzt ein Terminplugin für Werkstatttermine. Der Laden wünschte sich, dass bei jeder Buchung zusätzlich eine Nachricht an das Werkstatt-Tablet geht und dass Termine am Samstag einen Hinweis auf verkürzte Öffnungszeiten tragen. Statt das Plugin zu verändern, entstand ein kleines Zusatz-Plugin mit zwei Hooks: eine Action auf radwerk_termin_gebucht, die die Nachricht versendet, und ein Filter auf den Titel, der samstags den Hinweis ergänzt. Das Terminplugin wurde seitdem mehrfach aktualisiert, die Anpassungen funktionieren unverändert.

Typische Fehler mit Hooks

Der Klassiker ist der vergessene Rückgabewert in einem Filter: Die Funktion ergänzt etwas, gibt aber nichts zurück, und plötzlich sind alle Titel oder Inhalte leer. Ebenso häufig ist die falsche Anzahl von Argumenten. Wer in der Funktion die Beitrags-ID erwartet, aber beim Einhängen den vierten Parameter vergisst, bekommt nur den ersten Wert übergeben – PHP meldet dann einen Fehler wegen fehlender Argumente. Ein dritter Fehler betrifft den Zeitpunkt: Code, der auf eine Funktion eines anderen Plugins zugreift, läuft in der Hauptdatei zu früh, weil das andere Plugin vielleicht noch gar nicht geladen ist. Solcher Code gehört auf plugins_loaded oder später.

Schwerer zu finden sind Nebenwirkungen. Ein Filter auf the_content greift nicht nur im Hauptinhalt, sondern auch in Auszügen, Feeds und manchmal in Blöcken, die Inhalte anderer Beiträge anzeigen. Wer einen Hinweis nur unter dem Hauptinhalt einer Einzelseite will, prüft deshalb mit is_singular, in_the_loop und is_main_query. Und schließlich: Hooks in Schleifen oder bei jedem Aufruf erneut einhängen führt dazu, dass Funktionen mehrfach laufen und Texte doppelt erscheinen. Hooks werden einmal beim Start eingehängt – am besten gesammelt in einer Methode, die man auf einen Blick überblicken kann.

5. Häufige Fragen

Wie finde ich heraus, welche Hooks es gibt? Die Code-Referenz auf developer.wordpress.org listet alle Hooks des Kerns mit Parametern. Im Quellcode findet man sie durch Suchen nach do_action und apply_filters. Das Plugin Query Monitor zeigt zudem, welche Hooks beim aktuellen Seitenaufruf ausgelöst wurden und welche Funktionen daran hängen.

Wann sind Hooks zu spät? Viele Probleme entstehen, weil Code zu früh oder zu spät läuft. Inhaltstypen müssen auf init registriert werden; wer das erst auf wp_loaded tut, bekommt Fehler bei Links. Aussagen wie „ist das eine Einzelseite?“ funktionieren erst, nachdem die Abfrage gelaufen ist, also etwa ab template_redirect.

Kosten viele Hooks Leistung? Das Anhängen selbst kostet kaum etwas. Teuer wird es, wenn Funktionen an häufig aufgerufenen Filtern wie gettext aufwendige Arbeit erledigen. Solche Funktionen sollten sofort prüfen, ob sie zuständig sind, und andernfalls den Wert unverändert zurückgeben.

6. Übung zum Selbermachen

Öffnen Sie WordPress Playground und legen Sie im Ordner mu-plugins eine Datei an. Schreiben Sie einen Filter auf the_content, der unter jedem Beitrag – aber nicht auf Seiten – den Satz „Fragen? Rufen Sie uns an.“ ergänzt. Tipp: is_singular('post') hilft. Schreiben Sie danach einen zweiten Filter mit Priorität 5, der das Wort „Fahrrad“ fett setzt, und beobachten Sie, ob Ihr Hinweissatz davon betroffen ist. Tauschen Sie dann die Prioritäten.

Stand: September 2026, WordPress 7.1, PHP 8.3. Kursmaterial der Klarwerk Akademie. WordPress entwickelt sich schnell – maßgeblich ist die aktuelle Dokumentation auf developer.wordpress.org.