Tipos de hooks en WordPress: guía técnica real

Aprende los tipos de hooks WordPress, cómo funcionan actions y filters, y cuándo usar cada uno en tu desarrollo con ejemplos reales.

Qué son los hooks en WordPress y por qué importan

Si desarrollas con WordPress más allá de instalar plugins, en algún momento necesitas modificar comportamientos sin tocar el código fuente del core, un tema o un plugin de terceros. Ahí entran los hooks. Entender los tipos de hooks WordPress es lo que separa a un desarrollador que «hace cosas» de uno que construye soluciones mantenibles y escalables.

Un hook es, en esencia, un punto de enganche. WordPress ejecuta su código de forma secuencial y, en momentos clave de esa ejecución, lanza hooks para que tú puedas «colgar» tu propia lógica. Es un patrón de diseño conocido como patrón observer, muy extendido en ingeniería de software. WordPress lo implementa de forma especialmente accesible: no necesitas dominar programación orientada a objetos para empezar a usarlos.

El core de WordPress contiene más de 2.500 hooks documentados. WooCommerce añade varios cientos más. Y cada tema o plugin puede registrar los suyos propios. Conocer cómo se clasifican, cuándo se disparan y qué puedes hacer con ellos te da un control granular sobre prácticamente cualquier aspecto de un sitio.

Los dos tipos fundamentales: actions y filters

WordPress clasifica sus hooks en dos categorías claras: action hooks (acciones) y filter hooks (filtros). La diferencia no es cosmética; determina qué tipo de operación puedes realizar.

Action hooks: ejecutar código en un momento concreto

Un action hook te permite ejecutar una función en un punto específico del ciclo de ejecución de WordPress. No espera que devuelvas nada. Simplemente dice: «aquí pasa algo, si quieres hacer algo adicional, es tu momento».

La función que usas es add_action(). Recibe como mínimo dos argumentos: el nombre del hook y la función callback que quieres ejecutar.

Ejemplo real: quieres añadir un script de analytics en el <head> de tu sitio. Usarías el hook wp_head:

add_action( 'wp_head', 'mi_script_analytics' );
function mi_script_analytics() {
    echo '<script>/* código analytics */</script>';
}

Algunos de los action hooks más utilizados en desarrollo WordPress son:

• init — Se dispara después de que WordPress ha terminado de cargarse pero antes de enviar headers. Ideal para registrar custom post types y taxonomías.
• wp_enqueue_scripts — El lugar correcto para encolar hojas de estilo y scripts en el front-end.
• admin_menu — Permite añadir páginas al menú del panel de administración.
• save_post — Se ejecuta cada vez que se guarda un post. Útil para procesar metadatos personalizados.
• wp_footer — Justo antes de cerrar el </body>. Perfecto para scripts que no bloquean el renderizado.
• rest_api_init — Donde registras tus endpoints personalizados de la API REST.

La clave con las acciones es que no devuelven un valor al flujo principal. Ejecutan lógica lateral: insertar HTML, enviar un email, escribir un log, registrar un recurso.

Filter hooks: modificar datos antes de que se usen

Un filter hook intercepta un dato, te lo pasa, y espera que devuelvas ese dato (modificado o no). Si no devuelves nada, rompes la cadena y el dato se pierde, lo cual es un error frecuente en desarrolladores que empiezan con filtros.

La función es add_filter(), y la sintaxis es casi idéntica a add_action(), pero tu callback siempre debe retornar un valor.

Ejemplo: quieres añadir un texto automático al final de cada entrada:

add_filter( 'the_content', 'agregar_texto_final' );
function agregar_texto_final( $content ) {
    if ( is_single() ) {
        $content .= '<p>Gracias por leer.</p>';
    }
    return $content;
}

Filtros imprescindibles que todo desarrollador WordPress debería conocer:

• the_content — Filtra el contenido del post antes de mostrarlo. Uno de los más potentes y versátiles.
• the_title — Modifica el título de un post sobre la marcha.
• excerpt_length — Controla la longitud del extracto automático.
• body_class — Añade o elimina clases CSS al <body>. Muy útil para lógica condicional de estilos.
• wp_mail_from — Cambia la dirección «from» de los emails que envía WordPress.
• login_redirect — Define a dónde redirige WordPress tras un login exitoso.

Diferencias reales entre actions y filters

La confusión entre ambos tipos de hooks WordPress es comprensible porque comparten sintaxis y mecanismo interno. De hecho, internamente WordPress procesa ambos con la misma clase WP_Hook. Pero la distinción práctica es fundamental:

Un truco que uso para decidir cuál necesito: si la pregunta es «¿quiero hacer algo?», es una acción. Si la pregunta es «¿quiero cambiar algo?», es un filtro.

Prioridades y argumentos: control fino

Tanto add_action() como add_filter() aceptan dos parámetros adicionales que muchos desarrolladores ignoran: prioridad y número de argumentos.

La prioridad por defecto es 10. Un número menor significa que tu función se ejecuta antes; un número mayor, después. Esto es crítico cuando múltiples plugins o un tema enganchan al mismo hook. Si necesitas que tu filtro se aplique después de que un plugin de SEO modifique el título, pondrías una prioridad de 20 o superior.

add_filter( 'the_title', 'mi_modificacion_titulo', 20, 2 );

El cuarto parámetro (2 en el ejemplo) indica cuántos argumentos acepta tu callback. Algunos hooks pasan datos adicionales —como el ID del post— que solo recibes si declaras que los esperas.

Según la documentación oficial de WordPress para desarrolladores, no declarar correctamente el número de argumentos es una de las causas más comunes de errores silenciosos en plugins.

Hooks personalizados: crea los tuyos propios

No estás limitado a los hooks que WordPress define. Puedes crear tus propios hooks con do_action() y apply_filters(). Esto es especialmente relevante cuando desarrollas plugins o temas que otros desarrolladores van a extender.

// En tu plugin:
$precio = apply_filters( 'mi_plugin_precio_final', $precio_base, $producto_id );

// Otro desarrollador puede hacer:
add_filter( 'mi_plugin_precio_final', function( $precio, $id ) {
    if ( $id === 42 ) {
        return $precio * 0.9; // 10% descuento
    }
    return $precio;
}, 10, 2 );

Esta arquitectura extensible es lo que hace que el ecosistema WordPress sea tan flexible. Plugins como WooCommerce ofrecen centenares de hooks propios precisamente para que puedas personalizar el comportamiento sin modificar su código fuente.

Cómo localizar hooks disponibles en cualquier proyecto

Una de las preguntas más frecuentes es: ¿cómo sé qué hooks puedo usar? Hay varias estrategias:

• Buscar en el código fuente. Cualquier aparición de do_action() o apply_filters() define un hook disponible. Un simple grep en el directorio del plugin o tema te da la lista completa.
• Usar un plugin de debug. Herramientas como Query Monitor muestran todos los hooks que se disparan en cada carga de página, con sus callbacks asociados y prioridades.
• Consultar la referencia del código. El WordPress Code Reference en developer.wordpress.org documenta los hooks del core con contexto y ejemplos.
• Leer el código de WooCommerce. Si trabajas con tiendas, los archivos de templates de WooCommerce están plagados de do_action() en puntos estratégicos (antes del precio, después del botón de añadir al carrito, etc.).

Errores frecuentes al trabajar con hooks

Después de años trabajando con WordPress, estos son los fallos que veo repetirse:

No respetar el return en filtros

Ya lo mencioné, pero merece énfasis. Olvidar return $value; en un filter hook hace que el dato desaparezca. El contenido del post queda en blanco, el título se pierde, el email no tiene remitente. Y no hay error de PHP que te avise.

Enganchar demasiado pronto

Intentar usar add_action() en un momento en que WordPress todavía no ha registrado el hook objetivo. Por ejemplo, intentar modificar el menú de admin antes de que se dispare admin_menu. La solución: encierra tu lógica dentro del hook correcto.

Prioridades no planificadas

Cuando varios plugins compiten por el mismo hook sin gestionar prioridades, el resultado es impredecible. Si estás desarrollando algo que otros van a usar, documenta en qué prioridad engancha tu código.

Callbacks anónimos difíciles de desactivar

Si usas funciones anónimas (closures) como callback, después no puedes eliminarlas con remove_action() o remove_filter(). En código de producción, especialmente en plugins, usa funciones con nombre.

Cuándo usar hooks y cuándo no

Los hooks resuelven la mayoría de personalizaciones, pero no todo debe hacerse con hooks. Si necesitas una funcionalidad completamente nueva que no tiene relación con ningún punto de ejecución existente —como una integración compleja con un sistema externo—, probablemente necesitas un plugin completo con su propia arquitectura, no un add_action en functions.php.

Tampoco tiene sentido abusar de filtros para reescribir la salida HTML completa de un componente. Si necesitas cambiar radicalmente un template, es más limpio sobreescribir el archivo de plantilla que aplicar un filtro que reemplace todo el contenido.

El sistema de hooks de WordPress está diseñado para modificaciones quirúrgicas y extensiones modulares. Usarlo así produce código limpio. Forzarlo para todo produce espagueti.

Si estás evaluando cómo estructurar mejor un proyecto WordPress complejo, puedes revisar mis servicios de desarrollo WordPress para entender cómo abordo este tipo de arquitecturas.

// Sobre el autor

fernandodomecq

Desarrollador WordPress freelance especializado en WooCommerce, integraciones e IA. Escribo sobre proyectos web, agencias y buenas prácticas técnicas.

Ver todos los artículos →