Hooks de WordPress explicados: acciones y filtros con ejemplos que puedes probar hoy

Si alguna vez copiaste un fragmento de código para WordPress, seguro empezaba con add_action( o add_filter(. Son la base de todo: así funcionan los plugins, los temas y los snippets. Cuando los entiendes, dejas de copiar código a ciegas y empiezas a leerlo.

La idea: WordPress avisa en momentos clave

Mientras arma una página, WordPress va pasando por momentos: «estoy cargando», «estoy armando la cabecera», «voy a mostrar el título», «voy a mostrar el contenido», «estoy en el pie». En cada uno de esos momentos deja un gancho (eso significa hook) donde tu código se puede colgar.

Hay dos tipos de ganchos:

• Acciones (add_action): «en este momento, haz algo«. Por ejemplo, imprimir un código en la cabecera o enviar un correo cuando se publica una entrada.
• Filtros (add_filter): «este dato está a punto de usarse; ¿quieres cambiarlo?«. Por ejemplo, modificar el título, el contenido o la longitud del extracto.

Para recordar: una acción hace. Un filtro recibe, cambia y devuelve.

Anatomía de add_action

add_action( 'wp_footer', 'mi_aviso_en_el_pie', 10, 0 );

function mi_aviso_en_el_pie() {
	echo '<p style="text-align:center">Hecho con WordPress</p>';
}

1. 'wp_footer': el nombre del gancho. Este se ejecuta justo antes de cerrar la página.
2. 'mi_aviso_en_el_pie': la función que se ejecutará.
3. 10: la prioridad. Si varias funciones se cuelgan del mismo gancho, se ejecutan de menor a mayor. 10 es el valor por defecto.
4. 0: cuántos datos (argumentos) recibe tu función. Por defecto es 1.

La prioridad y el número de argumentos son opcionales. Casi siempre verás solo los dos primeros.

Anatomía de add_filter

add_filter( 'excerpt_length', 'mi_extracto_corto' );

function mi_extracto_corto( $longitud ) {
	return 25; // palabras
}

WordPress está a punto de cortar el extracto en 55 palabras (su valor por defecto). Antes de hacerlo, pasa ese número por el filtro excerpt_length. Nuestra función lo recibe en $longitud y devuelve 25. Resultado: extractos más cortos.

El error más común con filtros: olvidar el return. Si tu función no devuelve nada, el dato queda vacío. Con the_content, por ejemplo, todas tus entradas aparecerían en blanco.

Filtros con más de un dato

Algunos filtros entregan información extra. Por ejemplo, the_title entrega el título y el ID de la entrada. Para recibir ambos, hay que decirlo en el cuarto parámetro:

add_filter( 'the_title', 'mi_marca_destacada', 10, 2 );

function mi_marca_destacada( $titulo, $id ) {
	if ( is_admin() ) {
		return $titulo; // no tocar el panel
	}
	if ( is_sticky( $id ) ) {
		$titulo = '★ ' . $titulo;
	}
	return $titulo;
}

Este filtro agrega una estrella al título de las entradas fijadas en portada. Fíjate en el 2 al final de add_filter: sin él, la función recibiría solo $titulo y fallaría.

Funciones anónimas: la forma corta

Muchos snippets modernos escriben la función directamente dentro de add_action o add_filter:

add_filter( 'excerpt_length', function ( $longitud ) {
	return 25;
} );

Hace lo mismo y evita choques de nombres. La desventaja: no se puede «descolgar» después con remove_filter, porque no tiene nombre.

Quitar lo que otro colgó

Así como puedes colgar funciones, puedes descolgar las de WordPress, del tema o de un plugin, siempre que tengan nombre:

// WordPress agrega en la cabecera una etiqueta con su versión. La quitamos:
remove_action( 'wp_head', 'wp_generator' );

Para que funcione, el nombre del gancho, la función y la prioridad deben ser los mismos con los que se colgó.

Los ganchos que más vas a usar

• init (acción): WordPress terminó de cargar. Aquí se registran tipos de contenido, taxonomías y shortcodes.
• wp_enqueue_scripts (acción): el momento correcto para cargar CSS y JavaScript en el sitio.
• admin_enqueue_scripts (acción): lo mismo, pero en el panel.
• wp_head y wp_footer (acciones): imprimir algo en la cabecera o al pie, como un código de analítica.
• save_post (acción): se acaba de guardar una entrada.
• the_content y the_title (filtros): modificar contenido y título al mostrarlos.
• excerpt_length y excerpt_more (filtros): longitud del extracto y lo que aparece al final («[…]»).
• login_redirect (filtro): a dónde va el usuario al iniciar sesión.

Cómo leer cualquier snippet antes de pegarlo

1. ¿Acción o filtro? Si es filtro, verifica que haya un return.
2. ¿Qué gancho usa? Busca su nombre en developer.wordpress.org: la documentación oficial explica cuándo se ejecuta y qué datos entrega.
3. ¿Tiene condiciones? Funciones como is_admin(), is_singular() o is_user_logged_in() limitan dónde actúa. Sin ellas, el snippet actúa en todo el sitio.
4. ¿Imprime datos? Lo que se imprime debería pasar por esc_html(), esc_attr() o esc_url().
5. ¿Los nombres de funciones tienen prefijo? Una función llamada cambiar_titulo() puede chocar con otra. Mejor tusigla_cambiar_titulo().

Un truco para descubrir ganchos

El plugin Query Monitor, en su panel Hooks & Actions, muestra todos los ganchos que se ejecutaron en la página actual y qué funciones están colgadas de cada uno. Es como ver los cables detrás de la pared.

¿Encontraste un snippet y no entiendes qué hace? Pégalo en el foro y lo leemos juntos, línea por línea, antes de que lo uses.