Hooks de WordPress: qué son los actions y filters

Si alguna vez te has preguntado cómo es posible que un plugin modifique el comportamiento de WordPress sin tocar ni una línea de su código fuente, la respuesta está en los hooks de WordPress. Los hooks (ganchos, en español) son el mecanismo de extensión sobre el que se construye todo el ecosistema: temas, plugins y hasta el propio núcleo los usan constantemente para insertar funcionalidad o alterar datos en puntos concretos de la ejecución. Entenderlos es la frontera que separa a quien copia y pega fragmentos de código de quien realmente sabe qué está haciendo con su web. En esta guía vamos a ver qué son exactamente los actions y los filters, en qué se diferencian, cómo usarlos con ejemplos reales y funcionales, cómo controlar prioridades y argumentos, y cómo crear tus propios hooks para que tu código también sea extensible. Todo con código PHP probado que puedes adaptar a tu proyecto hoy mismo.

Qué son los hooks de WordPress y por qué existen

WordPress se diseñó desde el principio con una regla de oro: nunca modificar el núcleo. Si cada desarrollador editase los archivos de wp-includes para cambiar un comportamiento, cada actualización borraría esos cambios y mantener una web sería una pesadilla. La solución fue sembrar el código del núcleo con miles de puntos de enganche: momentos concretos de la ejecución en los que WordPress se detiene un instante y pregunta «¿alguien quiere hacer algo aquí?».

Eso es un hook: un punto de extensión con nombre propio. Cuando WordPress carga una página ejecuta, en orden, hooks como init, wp_loaded, template_redirect o wp_head. Tu código puede «engancharse» a cualquiera de ellos registrando una función de callback, y WordPress la ejecutará en ese momento exacto sin que tengas que tocar nada más.

El sistema descansa sobre dos familias:

• Actions (acciones): führen Code zu einem bestimmten Zeitpunkt aus. Sie geben nichts zurück; sie dienen dazu, tun Dinge (eine E-Mail senden, ein Skript einreihen, einen Beitragstyp registrieren).
• Filter (Filter): empfangen Daten, ändern sie und geben sie zurück. Sie dienen dazu, transformar Informationen (den Text eines Auszugs ändern, einen Titel ändern, eine Abfrage modifizieren).

Diese Unterscheidung ist die erste Frage, die du dir bei jedem Hook stellen solltest: Mache ich etwas oder ändere ich etwas?

Aktionen: Code zum richtigen Zeitpunkt ausführen

Eine Aktion wird mit add_action(), die mindestens zwei Parameter benötigt: den Namen des Hooks und die Funktion, die du ausführen möchtest. Sehen wir uns das klassische Beispiel an, wie man ein Stylesheet korrekt lädt:

<?php
function biblioweb_cargar_estilos() {
    wp_enqueue_style(
        'biblioweb-personalizado',
        get_stylesheet_directory_uri() . '/css/personalizado.css',
        array(),
        '1.0.0'
    );
}
add_action( 'wp_enqueue_scripts', 'biblioweb_cargar_estilos' );

Hier sagen wir WordPress: „wenn es Zeit ist, Frontend-Skripte und -Stile einzureihen (wp_enqueue_scripts), führe meine Funktion aus». Ein weiteres sehr häufiges Beispiel ist die Reaktion auf ein Ereignis, wie das Senden einer Benachrichtigung, wenn ein Beitrag veröffentlicht wird:

<?php
function biblioweb_avisar_publicacion( $post_id, $post ) {
    // Evitamos revisiones y autoguardados.
    if ( wp_is_post_revision( $post_id ) ) {
        return;
    }
    $asunto  = 'Nueva entrada publicada: ' . $post->post_title;
    $mensaje = 'Se ha publicado una entrada. Revísala aquí: ' . get_permalink( $post_id );
    wp_mail( 'editor@tudominio.com', $asunto, $mensaje );
}
add_action( 'publish_post', 'biblioweb_avisar_publicacion', 10, 2 );

Beachte die letzten beiden Parameter von add_action(): das 10 ist die Priorität und das 2 gibt an, wie viele Argumente unsere Funktion akzeptiert. Wir werden sie später im Detail sehen, da sie die Ursache für 90 % der Fehler bei Hooks sind.

Unverzichtbare Aktionen, die man kennen sollte

• init: WordPress ist bereits geladen; hier werden benutzerdefinierte Beitragstypen, Taxonomien und Shortcodes registriert.
• wp_enqueue_scripts: der richtige Zeitpunkt, um CSS und JS für das Frontend einzureihen.
• admin_init y admin_menu: Entsprechungen für den Administrationsbereich.
• wp_head y wp_footer: geben Inhalt in das <head> und bevor das <body>.
• save_post: wird beim Speichern jedes Beitrags ausgelöst; ideal zum Verarbeiten von Metadaten.
• wp_login y user_register: reagieren auf den Login und die Benutzerregistrierung.

Filter: Daten ändern, bevor sie verwendet werden

Ein Filter funktioniert genauso wie eine Aktion mit einem entscheidenden Unterschied: Deine Funktion empfängt einen Wert und muss es zurückgeben, geändert oder nicht. Wenn du das return, die Daten kommen leer an ihrem Ziel an und du wirst etwas kaputt machen (leere Auszüge, verschwundene Titel…). Es ist der häufigste Fehler, wenn man mit WordPress-Hooks beginnt.

Praktisches Beispiel: die Länge des Auszugs und den Text von „Weiterlesen“ ändern:

<?php
function biblioweb_longitud_extracto( $longitud ) {
    return 30; // palabras
}
add_filter( 'excerpt_length', 'biblioweb_longitud_extracto' );

function biblioweb_leer_mas( $more ) {
    return '&hellip; <a href="' . esc_url( get_permalink() ) . '">Seguir leyendo</a>';
}
add_filter( 'excerpt_more', 'biblioweb_leer_mas' );

Ein weiterer sehr nützlicher Fall: automatisch einen Hinweis am Ende des Inhalts jedes Beitrags hinzufügen, nur im Frontend:

<?php
function biblioweb_nota_final( $content ) {
    if ( is_singular( 'post' ) && in_the_loop() && is_main_query() ) {
        $nota = '<p class="nota-final">&iquest;Te ha resultado &uacute;til? Comp&aacute;rtelo o d&eacute;janos un comentario.</p>';
        return $content . $nota;
    }
    return $content;
}
add_filter( 'the_content', 'biblioweb_nota_final' );

Beachte die bedingten Prüfungen: the_content wird in vielen Kontexten angewendet (Feeds, Widgets, Seiten), und bedingungsloses Filtern führt dazu, dass deine Notiz dort angezeigt wird, wo sie nicht hingehört. Immer zurückgeben $content am Ende, auch wenn du es nicht änderst, ist es obligatorisch.

Filter, die du immer wieder verwenden wirst

• the_content y the_title: der Inhalt und der Titel der Beiträge.
• excerpt_length y excerpt_more: Kontrolle des Auszugs.
• body_class: fügt CSS-Klassen zu <body>.
• upload_mimes: erlaubt (oder blockiert) Dateitypen in der Mediathek.
• wp_mail_from y wp_mail_from_name: Absender der WordPress-E-Mails.
• login_errors: Fehlermeldung beim Login (nützlich, um Angreifern keine Hinweise zu geben).

Priorität und Argumente: Die beiden Zahlen, die alles ändern

Sowohl add_action() wie add_filter() akzeptieren vier Parameter:

add_filter( 'nombre_del_hook', 'mi_funcion', $prioridad, $num_argumentos );

Die Priorität ist wichtig, wenn mehrere Plugins dieselben Daten berühren. Wenn dein Filter über the_content nach einem anderen Plugin ausgeführt werden soll, verwende eine hohe Priorität (z.B. 99). Wenn du allen zuvorkommen musst, verwende 1. Die Anzahl der Argumente muss wiederum mit dem übereinstimmen, was du in der Signatur deiner Funktion deklarierst: wenn du 10, 3 aber deine Funktion nur einen Parameter akzeptiert, wird PHP einen fatalen Fehler auslösen.

Um eine Funktion zu entkoppeln, gibt es remove_action() y remove_filter(), mit einer strengen Bedingung: Es müssen genau derselbe Funktionsname und dieselbe Priorität übergeben werden, mit der sie registriert wurde:

<?php
// Quitar el generador de versión del head (lo añade el core con prioridad por defecto).
remove_action( 'wp_head', 'wp_generator' );

Wie du deine eigenen benutzerdefinierten Hooks erstellst

Hier ist der nächste Schritt: Neben der Nutzung von Hooks kannst du auch eigene erstellen. Wenn du ein Theme oder ein Plugin entwickelst, versehe deinen Code mit do_action() y apply_filters() ermöglicht es anderen (oder dir selbst in der Zukunft), ihn zu erweitern, ohne ihn zu berühren. So funktioniert WooCommerce, und deshalb ist sein Ökosystem riesig.

Eine eigene Action wird mit do_action():

<?php
// En tu plugin, tras procesar un pedido de ejemplo:
function biblioweb_procesar_solicitud( $solicitud_id ) {
    // ... lógica principal ...

    // Punto de extensión: cualquiera puede engancharse aquí.
    do_action( 'biblioweb_solicitud_procesada', $solicitud_id );
}

// Otro desarrollador (u otro archivo) se engancha:
add_action( 'biblioweb_solicitud_procesada', function ( $solicitud_id ) {
    error_log( 'Solicitud procesada: ' . $solicitud_id );
} );

Und ein eigener Filter, mit apply_filters(), der den Standardwert definiert und ihn jedem anbietet, der ihn ändern möchte:

<?php
function biblioweb_obtener_limite() {
    $limite = 25;
    // Nombre del filtro, valor por defecto y argumentos extra opcionales.
    return apply_filters( 'biblioweb_limite_resultados', $limite );
}

// Cualquier otro código puede ajustarlo sin tocar tu función:
add_filter( 'biblioweb_limite_resultados', function ( $limite ) {
    return 50;
} );

Zwei gute Praktiken: Benenne deine Hooks immer mit dem Namen deines Projekts, um Kollisionen zu vermeiden, und dokumentiere, welche Argumente jeder Hook übergibt. Ein undokumentierter Hook ist ein Hook, den niemand verwenden wird.

Wo du deinen Hook-Code platzieren solltest

Du hast drei vernünftige Optionen, von weniger bis mehr empfehlenswert je nach Fall:

1. Die functions.php eines Child-Themes: gültig für designbezogene Anpassungen (Auszüge, Body-Klassen). Wenn du das Theme wechselst, gehen sie verloren.
2. Ein Snippet-Plugin: die bequemste Option für die meisten. Tools wie WPCode, der Snippet-Manager, den wir ausführlich analysiert haben, ermöglichen es dir, jedes Snippet separat zu aktivieren und zu deaktivieren, mit Syntaxprüfung, die verhindert, dass die Website durch ein Semikolon zum Absturz gebracht wird.
3. Ein eigenes Plugin: das Richtige für Funktionalität, die das Theme überdauern soll: Custom Post Types, Integrationen, Geschäftslogik.

Was du niemals tun solltest, ist die functions.php des Parent-Themes oder natürlich die Core-Dateien zu bearbeiten. Wenn du anfängst und die essentielle Plugins, um mit WordPress zu starten, beginne damit, bevor du dich mit Code beschäftigst.

Häufige Fehler beim Arbeiten mit Hooks

• Den Return-Wert in einem Filter vergessen. Das typische Symptom: Inhalte oder Titel, die verschwinden. Jeder Filter gibt immer einen Wert zurück.
• Sich zu früh einklinken. Wenn du Benutzerfunktionen vor init oder Template-Funktionen vor wp, erhältst du Fehler oder leere Werte. Jeder Hook hat seinen Zeitpunkt im Ladezyklus.
• Argumente nicht deklarieren. Registrieren von add_action( 'save_post', 'mi_funcion', 10, 3 ) mit einer Funktion, die nur einen Parameter akzeptiert, führt in PHP 8 zu einem fatalen Fehler.
• Endlosschleifen. Aufrufen von wp_update_post() innerhalb eines Callbacks von save_post löst erneut aus save_post. Dies wird vermieden, indem der Hook vor dem Update entfernt und danach wieder hinzugefügt wird.
• Anonyme Callbacks, die du später nicht entfernen kannst. Anonyme Funktionen sind praktisch, aber remove_filter() kann sie nicht einfach entfernen. Für Code, den andere deaktivieren können sollen, verwende benannte Funktionen.

Um zu erkunden, welche Hooks existieren und welche Argumente sie übergeben, ist die offizielle Referenz von developer.wordpress.org über Hooks ist die ultimative Karte: Sie enthält die vollständige Liste der Actions und Filter des Cores mit ihrer Dokumentation.

Häufig gestellte Fragen

Was ist der tatsächliche Unterschied zwischen einer Action und einem Filter?

Eine Action führt Code an einem bestimmten Punkt im Ablauf aus und gibt nichts zurück: Sie dient dazu, Dinge zu tun. Ein Filter empfängt Daten, kann sie modifizieren und ist verpflichtet, sie zurückzugeben: Er dient dazu, Informationen zu transformieren. Intern verwenden beide dasselbe System (tatsächlich add_action() ruft auf add_filter()), aber konzeptionell ist es ratsam, sie als unterschiedliche Werkzeuge zu behandeln.

Kann ich Hooks verwenden, ohne programmieren zu können?

Du kannst bereits geschriebene Code-Snippets verwenden, indem du sie in ein Snippet-Plugin wie WPCode kopierst, das die Syntax vor dem Speichern validiert. Es ist jedoch wichtig, zumindest zu verstehen, was jede Zeile tut, um das Einfügen von bösartigem oder veraltetem Code zu vermeiden. WordPress-Hooks sind PHP: ein Minimum an Grundlagen gibt dir viel Autonomie.

Wie viele Hooks hat WordPress?

Der Core umfasst über 3.000 Actions und Filter, und die Zahl wächst mit jeder Version. Hinzu kommen die, die deine Plugins und dein Theme registrieren: WooCommerce zum Beispiel fügt Hunderte eigene hinzu. Man muss sie nicht auswendig lernen: Es genügt, die üblichen Dutzend zu kennen und den Rest in der offiziellen Dokumentation suchen zu können.

Beeinflussen Hooks die Leistung meiner Website?

Das System selbst ist sehr effizient; was sich negativ auswirkt, ist das, was du innerhalb des Callbacks tust. Eine aufwendige Abfrage, die an init wird bei jedem Seitenaufruf ausgeführt. Hänge deinen Code an den spezifischsten Hook an und verwende Bedingungen, um frühzeitig auszusteigen, wenn keine Aktion erforderlich ist.

Es ist ratsam, mindestens einmal pro Quartal ein vollständiges SEO-Audit durchzuführen. Sie sollten jedoch die Leistung Ihrer Keywords und den Zustand Ihrer Website wöchentlich überwachen. Inhaltsaktualisierungen und kleinere Optimierungen können regelmäßiger vorgenommen werden.

WordPress-Hooks sind die Sprache, in der sich Core, Themes und Plugins verständigen. Das Beherrschen des Paares Actions und Filter ermöglicht es dir, praktisch jedes Verhalten anzupassen, ohne den Quellcode zu berühren und ohne Angst vor Updates: Ressourcen in die Warteschlange stellen, auf Ereignisse reagieren, Inhalte transformieren und, wenn du den Sprung zur Entwicklung wagst, eigene Erweiterungspunkte anbieten mit do_action() y apply_filters()Beginne damit, die Beispiele dieser Anleitung in einer Testumgebung oder mit einem Snippet-Manager zu reproduzieren, achte auf die Prioritäten und den Rückgabewert der Filter und konsultiere die offizielle Dokumentation, wenn du unsicher bist, welche Argumente ein Hook übergibt. Von da an wird jedes Anpassungsproblem, auf das du in WordPress stößt, fast immer die gleiche Antwort haben: Dafür gibt es einen Hook.