Faragiri

Aprender Plugins WordPress

El orden de prioridad medido en una instalación real, las catorce funciones que ya cuelgan de the_content, y el olvido que vuelve un valor en nada.

4Secciones
4Minutos
5Profundidad

Un valor, tres dueños

Quién cambia el contenido, y en qué orden

Ninguno de los tres sabe que existen los otros, y lo único que decide qué ve el lector es un número que cada uno eligió por su cuenta.

  • el núcleo entrega el valor en do_blocks, wpautop y do_shortcode
  • el otro plugin y el tuyo reciben lo que sea que haya corrido antes
  • el tuyo devuelve el valor que el núcleo va a usar, o null si se olvida
  • El núcleo de WordPress
  • Otro plugin
  • Tu función
  • El núcleo de WordPressCatorce funciones sobre the_content, de la prioridad 8 a la 20
  • Otro pluginRegistrado en una prioridad que no se ve desde tu propio archivo
  • Tu funciónCorre antes o después de los dos, decidido solo por su número

El lado marcado es el que nadie ve desde adentro de un archivo de plugin. Query Monitor lo muestra, y es la única forma de saber si tu función corre antes o después de wpautop.

Un filtro le pasa un valor a tu función y se queda con lo que esa función devuelva. Medido en una instalación de WordPress real el 2026-09-05: un filtro que duplica el valor en prioridad 10 y otro que suma 5 en prioridad 20, aplicados sobre 100, contestan 205. La prioridad más baja corre primero, y el segundo filtro recibe lo que devolvió el primero.

Ahora la falla que produce la mayoría de los tickets de soporte de WordPress. Una función enganchada a un filtro que modifica el valor y se olvida de devolverlo hace que apply_filters conteste null. No el valor original, tampoco un error: null, entregado tal cual a lo que el núcleo iba a hacer con eso. Toda función enganchada a un filtro termina en un return, sin excepción.

Acciones y filtros son el mismo mecanismo, usado distinto

  • Una acción es un momento: algo pasó, hacé lo que quieras, no se espera nada de vuelta
  • Un filtro es un valor de paso: cambialo o no, y devolvelo de cualquier forma
  • Las dos corren en orden de prioridad, primero el número más bajo, y las dos ejecutan cada función registrada
  • El cuarto argumento de add_filter dice cuántos parámetros recibe tu función, y dejarlo en el valor por defecto de 1 mientras declarás dos parámetros es un error fatal justo cuando el hook se dispara

Ese último punto vale la pena nombrarlo porque el error aparece en un lugar que no tiene nada que ver: el hook se dispara adentro del núcleo, así que el mensaje señala un archivo que nunca abriste, y la causa es un número que falta en tu propio plugin.

Qué tan lleno está un hook antes de que llegues vos

Esta instalación tiene 711 hooks registrados en el momento en que se arma una página, y the_content por sí sola carga catorce funciones enganchadas. Leerlas en orden explica comportamientos que si no parecen magia: do_blocks en la prioridad 9 renderiza el contenido de los bloques, wptexturize y wpautop en 10 arman la tipografía y los párrafos, do_shortcode en 11, y wp_filter_content_tags en 12 agrega los atributos de las imágenes.

Por eso la prioridad es una decisión real y no un valor que se deja como viene. Una función en la prioridad 9 ve el contenido en bloques sin procesar; la misma función en 20 ve el HTML ya armado, con párrafos y shortcodes expandidos. Elegir el lado equivocado de wpautop es la razón por la que un elemento insertado termina envuelto en una etiqueta de párrafo que nadie pidió.

Qué instalar para ver los hooks en vez de adivinarlos

Query Monitor es la herramienta, gratis y de código abierto, y es el único plugin que vale la pena instalar en todo sitio de desarrollo. Lista los hooks que se dispararon en la petición actual con sus funciones, las consultas con quién las pidió, y los avisos de PHP, lo que convierte todo esto de lectura en observación directa. Reemplaza meter llamadas a error_log adentro de archivos del núcleo.

WP_DEBUG junto con WP_DEBUG_LOG es la segunda, gratis con WordPress, y viene apagada por defecto en cualquier instalación. Con eso encendido, el return olvidado de arriba aparece como un aviso en wp-content/debug.log en vez de una zona en blanco en la página. Reemplaza desarrollar con los errores escondidos, que es lo que trae por defecto y la razón por la que estos bugs duran tanto.

El hook que nadie encuentra a tiempo

Yolanda arma sitios en Cali y le entregaron un directorio de restaurantes con un plugin propio que agregaba una etiqueta de horario al final de cada reseña. La función devolvía el valor cambiado casi siempre, salvo en una rama que solo se activaba los fines de semana, y ahí faltaba el return; el sábado el texto de cada reseña desaparecía del sitio sin ningún error en pantalla.

La búsqueda que encuentra un hook toma un minuto: grep -rn "apply_filters\|do_action" wp-includes/ seguido de lo que estás buscando. Los nombres de los hooks son descriptivos, están en inglés, y ese vocabulario en particular vale la pena aprenderlo de memoria porque el mensaje de error del núcleo siempre llega en ese mismo idioma. Dónde viven esas funciones adentro del tema es Temas, el idioma en el que están escritas es PHP desde cero, y el sistema completo es WordPress.

Al lado de esto

Arriba de esto