WordPress · Desarrollo PHP · Guía para desarrolladores

Hooks de WordPress: qué son Actions y Filters y cómo utilizarlos

Los hooks de WordPress permiten ampliar el funcionamiento de una web mediante código PHP sin modificar directamente WordPress Core. Aprende qué son las acciones (actions) y los filtros (filters), cómo funcionan add_action() y add_filter(), qué papel cumplen las prioridades y cómo crear tus propios puntos de extensión.

Respuesta rápida: Un hook de WordPress es un punto de conexión que permite ejecutar código propio cuando ocurre un evento o modificar datos durante el procesamiento del sitio. Existen dos tipos principales: actions, que ejecutan tareas, y filters, que reciben un valor, permiten modificarlo y devuelven el resultado. Se registran normalmente con add_action() y add_filter(), respectivamente.

¿Qué son los hooks de WordPress?

Los hooks de WordPress son puntos de conexión definidos en WordPress Core, plugins y temas. Permiten que una parte del código interactúe con otra en momentos determinados de la ejecución, sin necesidad de editar los archivos originales del sistema.

Por ejemplo, puedes ejecutar una función cuando WordPress inicializa el sitio, cargar un archivo JavaScript en la parte pública, guardar información asociada a una entrada o modificar el título antes de mostrarlo. En lugar de alterar el código que realiza esas operaciones, registras una función propia en el hook correspondiente.

Este mecanismo es una de las bases de la extensibilidad de WordPress. Lo utilizan desarrolladores de plugins, temas y el propio núcleo para conectar funcionalidades de forma organizada.

En la API PHP de WordPress existen dos familias principales de hooks:

• Action hooks: ejecutan callbacks para realizar una tarea en un punto específico del proceso.
• Filter hooks: permiten transformar un valor y devolverlo para que el procesamiento continúe con el dato modificado.

¿Qué es un action en WordPress?

Un action o acción es un hook que permite ejecutar una función cuando WordPress llega a un punto determinado de su ejecución. La función conectada se conoce como callback.

La acción no está pensada para devolver un valor que reemplace el dato de WordPress. Su callback realiza una tarea: puede registrar información, enviar una notificación, preparar recursos o generar una salida, según el contexto y las reglas del hook.

Ejemplo básico de add_action()

El siguiente ejemplo registra una función en el hook wp_footer. WordPress ejecutará el callback cuando procese ese punto del pie de página:

function ciborg_mensaje_pie() {
    echo '<p>Contenido generado desde un action hook.</p>';
}

add_action( 'wp_footer', 'ciborg_mensaje_pie' );

El nombre de la función utiliza un prefijo propio para reducir el riesgo de colisiones con funciones de otros plugins o temas. Este ejemplo es demostrativo: antes de imprimir contenido en una ubicación real, comprueba que el hook se ejecute en el contexto que necesitas.

¿Qué es un filter en WordPress?

Un filter o filtro permite modificar un dato durante el procesamiento de WordPress. El callback recibe el valor, realiza la transformación necesaria y devuelve el resultado. Ese valor devuelto pasa a la siguiente parte del proceso.

Por ejemplo, puedes ajustar el título de una entrada antes de que se muestre, modificar la longitud de un extracto o transformar contenido generado por WordPress.

Ejemplo básico de add_filter()

Este filtro añade un texto al final del título de las entradas. Devuelve siempre el valor modificado:

function ciborg_modificar_titulo( $title ) {
    if ( is_admin() ) {
        return $title;
    }

    return $title . ' | Ciborg';
}

add_filter( 'the_title', 'ciborg_modificar_titulo' );

La comprobación de administración evita aplicar esta modificación indiscriminadamente en el escritorio. En un proyecto real, también debes decidir si el filtro debe actuar en listados, widgets, menús u otros contextos donde puede utilizarse the_title.

Diferencias entre actions y filters en WordPress

Aunque ambos utilizan el sistema de hooks y se registran de forma parecida, cumplen propósitos distintos. La pregunta práctica para elegir es: ¿necesitas ejecutar una tarea o modificar un valor?

Característica	Action	Filter
Objetivo	Ejecutar una tarea en un momento determinado.	Modificar un dato durante el procesamiento.
Registro habitual	add_action()	add_filter()
Callback	Realiza una operación; no devuelve un valor para sustituir el dato del hook.	Recibe un valor y devuelve el valor que debe continuar.
Ejemplos	Cargar scripts, ejecutar tareas, añadir una salida.	Modificar títulos, contenido, extractos o configuraciones.
Función que dispara el hook	do_action()	apply_filters()

Una precisión importante: internamente, add_action() utiliza el mecanismo de registro de filtros de WordPress, pero eso no significa que debas intercambiar acciones y filtros al programar. Debes respetar el contrato del hook que estás utilizando.

¿Cómo utilizar add_action() en WordPress?

La función add_action() conecta un callback con un action hook. Su estructura general es:

add_action(
    $hook_name,
    $callback,
    $priority,
    $accepted_args
);

Sus parámetros principales son:

• $hook_name: nombre de la acción donde quieres ejecutar tu función.
• $callback: función, método o callable que se ejecutará.
• $priority: orden de ejecución. El valor predeterminado es 10.
• $accepted_args: cantidad de argumentos que recibirá el callback. El valor predeterminado es 1.

Ejemplo: cargar un archivo CSS en el sitio

El hook wp_enqueue_scripts se utiliza para registrar y cargar scripts y estilos destinados a la parte pública del sitio:

function ciborg_cargar_estilos() {
    wp_enqueue_style(
        'ciborg-estilos',
        plugin_dir_url( __FILE__ ) . 'assets/css/estilos.css',
        array(),
        '1.0.0'
    );
}

add_action( 'wp_enqueue_scripts', 'ciborg_cargar_estilos' );

Este ejemplo está pensado para ejecutarse desde un archivo de plugin. Si lo incorporas a un tema, debes adaptar la ruta al mecanismo apropiado para obtener la URL de sus recursos.

¿Cómo utilizar add_filter() en WordPress?

La función add_filter() registra un callback en un filtro. Su estructura es equivalente a la de add_action():

add_filter(
    $hook_name,
    $callback,
    $priority,
    $accepted_args
);

Los parámetros tienen el mismo propósito: identificar el hook, indicar la función que se ejecutará, establecer el orden y definir cuántos argumentos aceptará el callback.

Ejemplo: modificar la longitud del extracto

El filtro excerpt_length permite cambiar el número de palabras utilizado para generar el extracto:

function ciborg_longitud_extracto( $length ) {
    return 25;
}

add_filter( 'excerpt_length', 'ciborg_longitud_extracto', 99 );

La prioridad 99 hace que el callback se ejecute después de callbacks con prioridades menores. No garantiza que sea el último: otro código puede registrar funciones con una prioridad superior o igual y ejecutarse después según el orden de registro.

¿Qué es la prioridad de un hook?

La prioridad determina el orden en el que se ejecutan los callbacks asociados al mismo hook. WordPress utiliza el valor 10 por defecto. Los números más bajos se ejecutan antes que los más altos.

Prioridad	Orden relativo
5	Se ejecuta antes que la prioridad 10.
10	Prioridad predeterminada.
20	Se ejecuta después de la prioridad 10.
99	Se ejecuta después de prioridades menores.

Cuando varios callbacks tienen la misma prioridad, se ejecutan en el orden en que fueron registrados. Ajustar la prioridad puede ser útil cuando una función depende del resultado de otra o cuando necesitas intervenir antes o después de una modificación existente.

¿Qué significa accepted_args?

El parámetro $accepted_args indica cuántos argumentos enviados por el hook recibirá la función callback. Debes revisar la documentación del hook para conocer los argumentos disponibles y configurar el número correcto.

Por ejemplo, el action save_post puede proporcionar el ID de la entrada, el objeto de la entrada y un indicador de actualización. Para recibir los tres argumentos:

function ciborg_al_guardar_entrada( $post_id, $post, $update ) {
    // Ejecutar una tarea utilizando los tres argumentos.
}

add_action( 'save_post', 'ciborg_al_guardar_entrada', 10, 3 );

El ejemplo muestra la firma del callback; en una implementación que modifique metadatos debes contemplar revisiones, guardados automáticos, permisos y validación de datos.

Hooks de WordPress más utilizados

WordPress dispone de numerosos hooks. Estos son algunos ejemplos frecuentes que conviene reconocer al desarrollar plugins o personalizaciones:

Hook	Tipo	Uso habitual
init	Action	Ejecutar tareas durante la inicialización de WordPress, como registrar tipos de contenido o taxonomías.
wp_enqueue_scripts	Action	Registrar y cargar scripts y estilos del sitio público.
admin_enqueue_scripts	Action	Cargar recursos en pantallas de administración.
wp_footer	Action	Ejecutar callbacks en el área del pie de página, si el tema llama al hook.
save_post	Action	Responder al guardado de una entrada o página.
the_content	Filter	Modificar el contenido que se procesa para mostrar una entrada.
the_title	Filter	Modificar el título en los contextos donde se aplica el filtro.
excerpt_length	Filter	Modificar la cantidad de palabras del extracto generado.

La disponibilidad y el momento exacto de ejecución dependen del hook y del contexto. Consulta la referencia oficial antes de conectar una función, especialmente para verificar argumentos y condiciones.

¿Cómo crear tus propios hooks en un plugin?

También puedes crear puntos de extensión para que otros desarrolladores amplíen tu propio plugin. Para ello, utiliza do_action() cuando quieras ejecutar callbacks y apply_filters() cuando quieras permitir que otros modifiquen un valor.

Crear un action personalizado

En el lugar donde quieres ofrecer el punto de extensión, llama a do_action() y pasa un nombre único. Puedes enviar argumentos adicionales:

// Dentro del código de tu plugin.
do_action( 'ciborg_orden_procesada', $order_id, $status );

Otro plugin puede conectarse a ese evento mediante add_action():

function ciborg_notificar_orden( $order_id, $status ) {
    // Ejecutar una tarea relacionada con la orden.
}

add_action( 'ciborg_orden_procesada', 'ciborg_notificar_orden', 10, 2 );

Crear un filter personalizado

Cuando necesitas que otros desarrolladores puedan cambiar un valor, utiliza apply_filters():

$mensaje = 'Tu solicitud fue recibida';

$mensaje = apply_filters(
    'ciborg_mensaje_confirmacion',
    $mensaje
);

Un plugin externo puede modificar el texto mediante add_filter() y devolver el resultado:

function ciborg_personalizar_confirmacion( $mensaje ) {
    return $mensaje . '. Gracias por contactarnos.';
}

add_filter(
    'ciborg_mensaje_confirmacion',
    'ciborg_personalizar_confirmacion'
);

Utiliza nombres únicos y documenta qué argumentos recibe cada hook propio. Así otros desarrolladores podrán extender tu código sin modificar sus archivos.

¿Existen hooks en JavaScript dentro de WordPress?

Sí. Además de la API PHP, WordPress dispone de una API de hooks para JavaScript, distribuida mediante el paquete @wordpress/hooks. Permite registrar y ejecutar acciones o filtros en código JavaScript, por ejemplo en extensiones del editor de bloques.

Los nombres de las funciones no son iguales a los de PHP. En JavaScript se utilizan métodos como addAction() y addFilter(), mientras que en PHP se utilizan add_action() y add_filter().

import { addFilter } from '@wordpress/hooks';

addFilter(
    'blocks.registerBlockType',
    'ciborg/mi-ajuste',
    ( settings ) => {
        return settings;
    }
);

Este ejemplo ilustra el registro de un filtro JavaScript; no añade por sí solo una modificación visible. Para utilizarlo en WordPress, el script debe cargarse correctamente y declarar las dependencias necesarias del paquete. Revisa la documentación del editor de bloques para conocer los hooks disponibles en cada extensión.

Buenas prácticas al trabajar con hooks de WordPress

Los hooks facilitan extender WordPress, pero una implementación incorrecta puede provocar errores, duplicación de funciones o problemas de seguridad. Aplica estas recomendaciones:

• No edites WordPress Core: utiliza hooks, plugins o temas hijo para mantener las personalizaciones separadas del núcleo.
• Usa prefijos únicos: evita nombres genéricos para funciones y hooks propios.
• Comprueba los argumentos: consulta la referencia del hook y ajusta $accepted_args a lo que realmente necesita tu callback.
• Devuelve el dato en los filtros: un filter debe retornar el valor original o el valor modificado.
• Elige bien la prioridad: evita cambiarla sin entender el orden de ejecución y las dependencias.
• Valida y sanitiza datos: especialmente al guardar información, procesar formularios o recibir parámetros externos.
• Verifica permisos y nonces: cuando una acción modifica información o responde a una solicitud del usuario, comprueba autorización y protección contra solicitudes falsificadas.
• Evita efectos secundarios en filtros: utiliza los filtros para transformar el valor, no para realizar operaciones ajenas a esa transformación.
• Prueba los cambios: utiliza un entorno de staging y activa los registros de depuración durante el desarrollo.

Cuando una personalización representa una funcionalidad propia del proyecto, suele ser más mantenible incorporarla en un plugin específico que depender del archivo functions.php de un tema que podría cambiarse en el futuro.

¿Cómo encontrar y depurar hooks en WordPress?

Cuando un callback no se ejecuta o modifica un resultado inesperado, sigue un proceso ordenado:

1. Verifica el nombre del hook: revisa la documentación oficial y confirma que el hook existe en el contexto donde se ejecuta tu código.
2. Comprueba el momento: registra el callback antes de que WordPress dispare el hook. Si lo registras después, puede que el evento ya haya ocurrido.
3. Revisa la firma: confirma cuántos argumentos entrega el hook y que coincidan con $accepted_args.
4. Revisa la prioridad: otro callback puede modificar el mismo dato antes o después del tuyo.
5. Activa la depuración: revisa errores PHP y registros del servidor en un entorno de pruebas.
6. Aísla conflictos: prueba temporalmente con un tema y plugins mínimos en staging para identificar interferencias.

WordPress dispone de funciones como has_action() y has_filter() para comprobar callbacks asociados a un hook. También existen remove_action() y remove_filter() para retirar callbacks previamente registrados, siempre que se conozcan correctamente el hook, callback y prioridad.

Preguntas frecuentes sobre hooks de WordPress

1. ¿Qué es un hook en WordPress?

Es un punto de conexión en WordPress Core, un plugin o un tema que permite ejecutar código propio o modificar datos durante un momento específico del procesamiento.

2. ¿Cuáles son los dos tipos de hooks de WordPress?

Los dos tipos principales de hooks PHP son actions y filters. Las actions ejecutan tareas; los filters permiten modificar un valor y devolverlo.

3. ¿Cuál es la diferencia entre add_action() y add_filter()?

add_action() registra una función para ejecutar una tarea cuando se dispara una acción. add_filter() registra una función que recibe un valor, lo puede modificar y debe devolverlo.

4. ¿Qué hace do_action() en WordPress?

do_action() dispara una acción y ejecuta los callbacks que se hayan registrado en ese hook mediante add_action().

5. ¿Qué hace apply_filters() en WordPress?

apply_filters() aplica un filtro a un valor y devuelve el resultado después de que se ejecutan los callbacks registrados con add_filter().

6. ¿Qué significa la prioridad en add_action() y add_filter()?

Es el número que determina el orden de ejecución de los callbacks asociados a un mismo hook. El valor predeterminado es 10; las prioridades menores se ejecutan antes que las mayores.

7. ¿Para qué sirve accepted_args?

Define cuántos argumentos del hook recibirá el callback. Debe coincidir con la cantidad de argumentos que tu función necesita y que el hook proporciona.

8. ¿Puedo crear mis propios hooks en un plugin?

Sí. Puedes usar do_action() para crear un punto de ejecución y apply_filters() para ofrecer un valor que otros desarrolladores puedan modificar.

9. ¿Dónde se recomienda agregar hooks personalizados?

Depende del objetivo. Para una funcionalidad que debe mantenerse aunque cambies de tema, lo más adecuado suele ser un plugin propio. Para personalizaciones estrictamente visuales o dependientes del tema, puede corresponder un tema hijo.

10. ¿Los hooks de WordPress también existen en JavaScript?

Sí. WordPress ofrece la API @wordpress/hooks para acciones y filtros JavaScript, utilizada entre otros contextos por extensiones del editor de bloques.

11. ¿Se puede eliminar un hook registrado?

Sí. Puedes utilizar remove_action() o remove_filter(), pero debes indicar el hook, el callback exacto y la prioridad con la que se registró.

12. ¿Es necesario modificar archivos de WordPress para usar hooks?

No. La finalidad de los hooks es permitir extensiones desde plugins, temas o código personalizado sin editar directamente los archivos del núcleo de WordPress.

Documentación oficial de WordPress

Para consultar la definición, los parámetros y los hooks disponibles, utiliza la documentación de desarrollo de WordPress:

• Plugin Handbook: Hooks
• Plugin Handbook: Actions
• Plugin Handbook: Filters
• Referencia de add_action()
• Referencia de add_filter()
• Hooks y filtros del editor de bloques

Guía técnica de Ciborg sobre la API de hooks de WordPress. Los ejemplos son ilustrativos y deben adaptarse al hook, versión, tema, plugins y contexto de ejecución de cada proyecto. Prueba los cambios en un entorno de desarrollo antes de utilizarlos en producción.