Guía de los hooks de WordPress: acciones y filtros

Qué son los hooks de WordPress

El sistema de hooks de WordPress es la base que te permite ampliar y modificar el sistema de WordPress sin cambiar directamente el código fuente. Los hooks son puntos en el código de WordPress donde puedes enganchar tus propias funciones, que se ejecutarán en un momento concreto o modificarán los datos que atraviesan el sistema. Sin los hooks, cada personalización requeriría modificar directamente los archivos del núcleo de WordPress, que se perderían con cada actualización.

Existen dos tipos de hooks: las acciones (actions) y los filtros (filters). Las acciones te permiten ejecutar código en un momento concreto del ciclo de vida de WordPress, mientras que los filtros te permiten modificar datos antes de que se muestren o se guarden. Comprender estos dos conceptos es clave para todo desarrollador de WordPress porque son la base para crear temas, plugins y funcionalidades personalizadas.

Acciones: ejecutar código en el momento oportuno

Cómo funcionan las acciones

Un hook de acción es un lugar en el código de WordPress donde se coloca una llamada a la función do_action. Cuando WordPress llega a ese punto durante la ejecución, comprueba si hay funciones enganchadas a ese hook y las ejecuta en orden de prioridad. Por ejemplo, la acción wp_head se dispara dentro de la etiqueta head de cada página, wp_footer se dispara antes de la etiqueta de cierre body, e init se dispara al inicio de cada carga de WordPress, después de que se carguen todos los plugins.

Uso de add_action

La función add_action toma cuatro parámetros: el nombre del hook, la función de retorno (callback), la prioridad y el número de argumentos. La prioridad determina el orden de ejecución cuando hay varias funciones enganchadas al mismo hook, con un valor por defecto de 10, donde un número menor significa una ejecución más temprana. Por ejemplo, si quieres añadir el código de Google Analytics a la cabecera del sitio, engancha la función al hook wp_head con prioridad 1 para que se ejecute entre las primeras. Si quieres añadir CSS después de todos los plugins, usa la prioridad 99.

Los hooks de acción más comunes

• init: Se dispara al inicio de cada petición tras cargarse los plugins. Ideal para registrar tipos de contenido personalizados, taxonomías y shortcodes.
• wp_enqueue_scripts: La forma correcta de añadir archivos CSS y JavaScript en el frontend. Usa las funciones wp_enqueue_style y wp_enqueue_script para gestionar dependencias y evitar duplicados.
• admin_init: Se dispara al inicio de cada página del administrador. Úsalo para registrar los ajustes del plugin, comprobar permisos o hacer redirecciones.
• save_post: Se dispara cuando se guarda o actualiza una entrada. Ideal para guardar metadatos personalizados, validar contenido o enviar notificaciones.
• wp_login y wp_logout: Se disparan al iniciar y cerrar sesión el usuario. Úsalos para registrar actividad, redirecciones o limpiar la caché.
• template_redirect: Se dispara antes de cargar la plantilla. Ideal para redirecciones personalizadas o comprobaciones de acceso a páginas.

Filtros: modificación de datos

Cómo funcionan los filtros

Un hook de filtro funciona de forma parecida a un hook de acción pero con una diferencia clave: el filtro recibe datos, los modifica y devuelve los datos modificados. WordPress usa la función apply_filters para pasar los datos por todas las funciones de filtro enganchadas. Toda función de filtro debe devolver un valor porque, de lo contrario, los datos quedan vacíos. Por ejemplo, el filtro the_content pasa el contenido de la entrada por todas las funciones enganchadas antes de mostrarlo, lo que permite a los plugins añadir botones de compartir en redes sociales, entradas relacionadas o anuncios dentro del contenido.

Uso de add_filter

La función add_filter tiene una sintaxis idéntica a add_action: nombre del hook, función de retorno, prioridad y número de argumentos. La diferencia clave es que la función de retorno debe recibir al menos un argumento que represente los datos a filtrar y debe devolver los datos modificados u originales. Si tu función de filtro no devuelve un valor, los datos se perderán, lo que puede romper el sitio. Prueba siempre las funciones de filtro para asegurarte de que devuelven el valor correcto incluso en los casos límite.

Los hooks de filtro más comunes

• the_content: Filtra el contenido de la entrada antes de mostrarlo. Los plugins de formato, los shortcodes y las modificaciones de contenido usan este filtro.
• the_title: Filtra el título de la entrada. Úsalo para añadir prefijos, sufijos o dar formato a los títulos de manera programática.
• wp_mail: Filtra los parámetros del correo antes de enviarlo. Puedes modificar los destinatarios, el asunto, el contenido o las cabeceras del correo.
• login_redirect: Filtra la URL a la que se redirige al usuario tras iniciar sesión. Úsalo para redirecciones personalizadas según el rol del usuario.
• excerpt_length: Filtra la longitud del extracto generado automáticamente. El valor por defecto es de 55 palabras.
• upload_mimes: Filtra los tipos de archivo permitidos para subir. Úsalo para añadir soporte de SVG u otros formatos.

Crear tus propios hooks

Hooks de acción personalizados

Al desarrollar un plugin o un tema, crear tus propios hooks permite que otros desarrolladores amplíen tu funcionalidad sin cambiar tu código. Coloca llamadas a do_action en los lugares donde quieras habilitar extensiones, por ejemplo antes y después de mostrar un formulario, antes de guardar datos o después de procesar un pedido. Nombra los hooks con el prefijo de tu plugin para evitar conflictos con otros plugins, por ejemplo myplugin_pre_save_data. Documenta los hooks disponibles con una descripción de cuándo se disparan y qué argumentos pasan.

Hooks de filtro personalizados

Usa apply_filters en los lugares donde quieras habilitar la modificación de datos. Por ejemplo, si tu plugin genera una lista de elementos, pasa el array de elementos por un filtro antes de mostrarlo. Otros desarrolladores pueden enganchar un filtro para añadir, eliminar o modificar elementos. Para cada filtro, documenta con claridad el tipo de dato que se filtra, el formato del valor de retorno esperado y el contexto en el que se usa el filtro. Esto hace que tu plugin sea agradable de ampliar y reduce la necesidad de modificaciones directas.

Desarrollo de plugins con hooks

Estructura de un plugin

Todo plugin de WordPress comienza con un comentario de cabecera que contiene el nombre del plugin, la descripción, la versión, el autor y la licencia. El archivo principal del plugin normalmente registra los hooks en el constructor de la clase o en una función de inicialización. Organiza el código en clases con métodos para cada funcionalidad y usa el constructor para registrar todos los hooks en un solo lugar. Esto hace que el código sea legible y más fácil de mantener porque puedes ver todos los hooks en un mismo sitio.

Activación y desactivación

WordPress proporciona hooks especiales, register_activation_hook y register_deactivation_hook, que se disparan al activar y desactivar el plugin. Usa el hook de activación para crear tablas de base de datos, establecer opciones por defecto y programar tareas cron. Usa el hook de desactivación para limpiar las tareas cron programadas y los datos temporales. Para una eliminación completa de los datos al borrar el plugin, crea un archivo uninstall.php que elimine las opciones de la base de datos, las tablas personalizadas y los archivos subidos.

Buenas prácticas

Usa siempre prefijos para los nombres de funciones y clases para evitar conflictos con otros plugins. Comprueba si un hook existe antes de registrarlo para evitar errores. Usa has_action y has_filter para comprobar si alguien ya está enganchado a un hook concreto. Elimina hooks con remove_action y remove_filter cuando necesites modificar el comportamiento de otro plugin o tema. La prioridad es clave al eliminar: debes usar la misma prioridad utilizada al añadir.

Depuración de hooks

Herramientas de depuración

El plugin Query Monitor es una herramienta indispensable para depurar hooks, ya que muestra todos los hooks registrados, el orden de ejecución y el tiempo que consume cada hook. La constante WP_DEBUG en wp-config.php habilita la visualización de los errores y advertencias de PHP que ayudan a identificar problemas con los hooks. El plugin Debug Bar añade un panel en la barra de administración con información sobre los hooks, las consultas a la base de datos y el uso de memoria. Para una depuración avanzada, Xdebug con VS Code permite establecer puntos de interrupción dentro de las funciones de retorno de los hooks.

Errores comunes

El error más común es una función de filtro que no devuelve un valor, lo que resulta en contenido vacío. Otro error frecuente es un número de argumentos no coincidente entre el registro del hook y la función de retorno. Se produce un bucle infinito cuando un filtro modifica los datos de una manera que vuelve a disparar el mismo filtro. Usa una variable estática o un indicador (flag) para evitar la recursión. Una prioridad equivocada puede hacer que tu función no funcione porque un hook anterior cambió los datos de forma inesperada. En los planes de alojamiento WordPress de BeoHosting tenemos un entorno optimizado para el desarrollo de plugins, con soporte para herramientas de depuración y suficiente memoria PHP para cadenas de hooks complejas.

Conclusión

El sistema de hooks de WordPress es un mecanismo potente y elegante que permite una ampliación ilimitada de WordPress. Las acciones te dan la capacidad de ejecutar código en el momento oportuno, mientras que los filtros permiten modificar datos en cualquier punto del sistema. Comprender los hooks es clave para la transición de usuario a desarrollador y abre la puerta a la creación de plugins y temas profesionales. Empieza por los hooks más utilizados, experimenta con la personalización y construye gradualmente funcionalidades más complejas. Si acabas de instalar WordPress, consulta nuestra guía de instalación.