¿QUÉ SON LOS GANCHOS (HOOKS) DE WORDPRESS Y CÓMO FUNCIONAN?

Los ganchos son lo que WordPress usa para permitir que un fragmento de código interactúe y/o modifique otro fragmento de código.

Por ejemplo, un plugin puede modificar otro fragmento de código que ejecute WordPress. WordPress también hace un uso extensivo de ganchos para modificar su propio código.

Los ganchos se denominan eventos (como save_post) a los que los desarrolladores pueden conectar funciones.

El nombre es la referencia que utiliza para conectar (o enganchar) su función. Cuando se ejecuta el gancho, en un momento determinado del proceso de carga de WordPress, se ejecutan las funciones añadidas al gancho.

Las funciones que conectamos a un gancho se conocen como «callbacks», que yo suelo denominar «llamadas de retorno», en el sentido de que el proceso de ejecutar un gancho, llama a su función para que se ejecute.

Se pueden añadir varias «callbacks» a un gancho, por lo tanto necesitamos una forma de ordenar estas «llamadas de retorno» para poder determinar cuál es la primera, la última y la intermedia.

Los ganchos de WordPress nos permiten asignar a cada llamada de retorno un número de prioridad (el valor predeterminado si no se añade una prioridad es 10). Por lo tanto, las «callbacks» añadidas a un gancho con una prioridad de 20 se ejecutarán después de las añadidas con una prioridad de 10.

¿CUÁLES SON LOS DISTINTOS TIPOS DE GANCHOS?

Hay dos tipos de ganchos en WordPress, acciones y filtros. Son muy similares, pero se comportan de una manera ligeramente diferente y por lo tanto vale la pena señalar la diferencia. Echemos un vistazo a cada uno.

Ganchos de acción (action hooks)

Las acciones en WordPress nos permiten añadir datos o cambiar la forma en que funciona el código extensible de WordPress o de otros.

Cualquier llamada de retorno (recuerda que son sólo funciones) añadida a una acción se ejecuta en un punto específico durante la carga de WordPress.

Las llamadas de retorno añadidas a las acciones podrían prácticamente hacer cualquier cosa, por ejemplo, podría hacer eco de algún contenido en un momento dado, insertar algo en la base de datos de WordPress o incluso interactuar con un servicio externo.

Verás ganchos de acción en WordPress llamados que usan la función do_action(). Las llamadas de retorno se conectan a las acciones con la función add_action(). Las llamadas de retorno también pueden eliminarse usando la función remove_action().

Ganchos de filtro (filter hooks)

Los filtros en WordPress son para cambiar datos durante la ejecución de WordPress.

Una llamada de retorno conectada con un filtro aceptará datos en forma de variable, hará algunos cambios a esos datos, y luego devolverá la variable (esto funciona así para que otras llamadas de retorno conectadas al filtro también puedan usarla).

Las llamadas de retorno añadidas a los filtros modificarán los datos que proporciona el gancho, tales como modificar los argumentos de una consulta o cambiar el valor de una cadena.

Verás ganchos de filtro en WordPress a los que se llama usando la función apply_filters(). Las llamada de retorno se conectan a los filtros con la función add_filter(). Las llamadas de retorno también se pueden eliminar utilizando la función remove_filter().

La diferencia entre «acción» y «filtro» en WordPress

La mayor diferencia entre acciones y filtros, y lo importante a recordar como desarrollador, es que con los filtros, las llamadas de retorno siempre deben devolver los datos que se pueden filtrar como una variable.

Las llamadas de retorno asociadas a una acción no necesitan devolver nada.

AÑADIR FUNCIONES DE LLAMADAS DE RETORNO A UN GANCHO DE ACCIÓN O FILTRO

Echemos un vistazo a cómo podemos conectarnos a WordPress usando el sistema de ganchos para añadir nuestra propia funcionalidad o modificar la funcionalidad existente, añadiendo llamadas de retorno mediante acciones y filtros.

A continuación verás un ejemplo de cada uno de ellos.

Un ejemplo de acción

Para ayudarte a entender cómo funcionan los ganchos de acción, echemos un vistazo a un ejemplo práctico. La página de inicio de sesión normal de WordPress es tal que así.

A menudo te vas a encontrar con clientes que quieren incluir más información en la página de inicio de sesión, por ejemplo, para recordar a los usuarios qué dirección de correo electrónico deben usar para acceder.

Añadir esto debajo del formulario de inicio de sesión es lo ideal. WordPress nos permite hacer esto gracias al uso de una acción. Cuando WordPress produce el contenido del formulario de inicio de sesión, incluye la siguiente línea de código:

1	do_action( ‘login_footer’ );

Esto significa que podemos conectar una función de llamada de retorno a este gancho de acción para mostrar más contenido en la página.

Por ejemplo, podríamos añadir una simple frase de instrucciones con el siguiente código:

1234567891011

/** * Añade un mensaje al pie de página del formulario de acceso. */function ayudawp_login_footer_message() { // muestra tu mensaje en el pie del área de acceso. ?> <p style=»border-top: 1px solid #0085ba; margin: 0 auto; width: 320px; padding-top: 10px;»>Utiliza tu correo @ayudawp.com para acceder.</p> <?php}add_action( ‘login_footer’, ‘ayudawp_login_footer_message’ );

Ahora tu página de inicio de sesión se verá así, con algo de contenido personalizado en el pie de página.

Un ejemplo de filtro

Para ayudarte a entender cómo funcionan los filtros de acción, echemos un vistazo a un ejemplo práctico.

En las pantallas del editor de entradas clásico de WordPress, verás que en la entrada donde añades el título de la entrada, hay un texto de marcador de posición que dice «Introduce el título aquí».

Cuando WordPress genera esto (en el código) lo hace con este código:

1	apply_filters( ‘enter_title_here’, __( ‘Enter title here’ ), $post );

Debido a que la cadena «Enter title here» se ejecuta a través de un filtro (podemos decirlo porque está envuelta en apply_filters()), esto significa que podemos cambiarla, conectando una función de llamada de retorno al filtro. Se parecería a esto.

1234567891011121314

/** * Altera el texto de introduce el título aquí. * en el editor clásico de WordPress. * * @param  string $title La cadena de texto actual. * @return string        La cadena de texto modificada. */function ayudawp_title_here( $title ) { // define una nueva cadena para el texto. $title = __( ‘Pon aquí el título de tu artículo’, ‘text-domain’ ); // devuelve el título al gancho. return $title;}add_action( ‘enter_title_here’, ‘ayudawp_title_here’, 10 );

En este fragmento de código puedes ver que estamos asignando un nuevo valor (una cadena de lo que queremos que sea el marcador de posición en este caso) a la variable $title, y luego regresamos a la variable.

Con esta ejecución ahora podemos ver que la pantalla de edición clásica de entradas refleja el cambio en el texto del marcador de posición del título de la entrada.

CÓMO ELIMINAR LAS FUNCIONES DE LLAMADA DE RETORNO DE UN GANCHO DE ACCIÓN O DE FILTRO

Ahora echemos un vistazo a cómo podemos conectarnos a WordPress usando el sistema de ganchos para eliminar la funcionalidad añadida por otros o por WordPress mismo, eliminando las llamadas de retorno mediante acciones y filtros.

Esta es la belleza del sistema de ganchos en WordPress porque cuando un desarrollador utiliza un gancho para añadir funcionalidad, otro desarrollador puede eliminar esa funcionalidad de una manera segura, sin cambiar directamente el código original.

Al eliminar filtros o acciones de WordPress, debes añadir a tu función de eliminación los mismos argumentos con los que se añadió la llamada de retorno, incluyendo la prioridad y el número de argumentos que se pasan a la llamada de retorno. Si no coinciden, significa que la eliminación no tendrá éxito.

A continuación veremos ejemplos de cómo eliminar las llamadas de retorno añadidas mediante filtros y acciones.

Ejemplo de eliminación de una acción

Si alguna vez has examinado el código fuente de una web hecha con WordPress te habrás dado cuenta de que tiene un elemento meta ‘generator‘ en la cabecera de la página que indica que WordPress la ha generado, incluyendo la versión de WordPress que se está utilizando.

Puesto que esto se añade usando un gancho, significa que los desarrolladores pueden eliminarlo usando el sistema de ganchos en WordPress. Para eliminar esto podríamos usar el siguiente código

1	remove_action( ‘wp_head’, ‘wp_generator’);

Lo puedes poner en un plugin o incluso en el archivo functions.php de tu tema.

Este código elimina la función de devolución de llamada wp_generator que se añade al gancho wp_head en WordPress. La función remove_filter() funciona de la misma manera.

NOTAS SOBRE ESTILOS DE PROGRAMACIÓN

Una cosa que algunos que empezáis a desarrollar en WordPress me habéis dicho, y que incluso yo me he preguntado a veces curioseando en plugins de otros, y que confunde, es que parece como si otros desarrolladores usaran ganchos de diferentes maneras.

Pero cuando miras muchos de esos códigos, y te aseguro que he visto muchos, te das cuenta de que es simplemente una forma diferente de escribir el código, más que una manera diferente de usarlos en términos de funcionalidad.

Cuando se engancha a una acción en WordPress (añadiendo su llamada de retorno) hay dos partes en el código.

1. Declarar su función que desea añadir al gancho
2. Llamar a la función add_action o apply_filters, que declara el nombre de la función que desea enganchar.

Muchos desarrolladores las escriben en el orden anterior, que es mi forma favorita. Declaras la función primero y luego directamente debajo de esa declaración la adjuntas a la acción.

Sin embargo, a menudo verás el código escrito con la función conecta primero a la acción y luego la declara debajo. Esto no influye en nada y no hay una manera correcta o incorrecta de hacerlo, sólo preferencias personales, manías si quieres.

Algunos desarrolladores incluso declaran todas las funciones enganchadas (las llamadas de retorno adjuntas a los ganchos) en uno o varios archivos y luego tienen todas las llamadas add_action o apply_filter en otro archivo.

Una vez más, esto es sólo una preferencia del desarrollador, aunque yo prefiero tener la declaración de la función y estar enganchado a la acción o filtrarlo juntos en el mismo lugar.

Lo último que puedes ver es un estilo de escritura que se parezca a esto:

123	add_action( ‘init’, function() {    // Hacer algo.});

En este ejemplo, puedes ver que la función adjunta al gancho init en WordPress no tiene nombre.

Se está declarando justo dentro de la llamada a add_action en lugar de ser declarado arriba o abajo y luego se le hace referencia.

Esto se llama funciones anónimas. Yo no recomendaría usarlos con los ganchos de WordPress porque hace que las funciones de llamada de retorno sean difíciles de desenganchar, ya que no tienen un nombre al que se pueda hacer referencia.

De hecho, si piensas subir un plugin a WordPress.org es una práctica no permitida. Todas las funciones deben tener un nombre único.

¿CÓMO FUNCIONAN LOS GANCHOS?

Al principio, puede ser difícil entender cómo funcionan los ganchos, y por lo tanto para tratar de ayudarte a entender esto voy a resumir en pasos sencillos lo que sucede cuando se dispara un gancho de WordPress (esto es un término de desarrollador para definir la ejecución de las funciones do_action y apply_filters).

1. WordPress busca todas las funciones de llamada de retorno asociadas a este gancho en particular. Piensa en ello como si los añadieras a una lista invisible.
2. WordPress busca cualquier llamada para eliminar acciones o filtros de este gancho, y si hay llamadas para remove_action o remove_filter para este gancho, elimina estas llamadas de retorno de la lista.
3. A continuación, se hace referencia a la prioridad de las llamadas de retorno añadidas y las llamadas de retorno se colocan en la lista en orden de prioridad, la llamada de retorno con la prioridad más baja va en primer lugar en la lista y la llamada de retorno con la prioridad más alta va en último lugar y todo lo demás en el medio en orden – de menor a mayor.
4. WordPress ahora tiene una lista de funciones de llamadas de retorno que ejecutar en este punto del proceso de carga y lo hace, ejecutando cada función de llamada de retorno después de la anterior.

Como puedes ver en la lista anterior, el uso de ganchos de WordPress es un sistema muy eficiente porque no se ejecutan funciones de llamadas de retorno hasta el último paso.

Esto significa que añadir y eliminar las llamadas de retorno de la lista invisible es muy eficiente, ya que las llamadas de retorno reales no se ejecutan hasta que tengamos una lista definitiva de lo que realmente necesitamos ejecutar.

PASANDO VARIABLES A FUNCIONES DE LLAMADA DE RETORNO

Los ganchos son excelentes para permitir a los desarrolladores ejecutar código en ciertos puntos del proceso de carga de WordPress. Sin embargo, pueden ser aún más útiles porque ciertos ganchos proporcionan variables a las llamadas de retorno.

Estas variables permiten que las llamadas de retorno hagan mucho más, a veces apuntando a cosas específicas y a veces cambiando datos en WordPress. Echemos un vistazo a cómo funciona esto.

Volvamos atrás y echemos un vistazo a nuestro ejemplo de filtro anterior, en el que observamos cómo cambiar el texto predeterminado del marcador de posición del título de la entrada en las pantallas de administración.

1234567891011121314

/** * Altera el texto de introduce el título aquí. * en el editor clásico de WordPress. * * @param  string $title La cadena de texto actual. * @return string        La cadena de texto modificada. */function ayudawp_title_here( $title ) { // define una nueva cadena para el texto. $title = __( ‘Pon aquí el título de tu artículo’, ‘text-domain’ ); // devuelve el título al gancho. return $title;}add_action( ‘enter_title_here’, ‘ayudawp_title_here’, 10 );

Esto es genial, pero por supuesto, cambiaría el texto del marcador de posición para todos los tipos de entradas en WordPress – entradas, páginas y también a cualquier otro tipo de contenido personalizado.

¿Qué pasaría si quisiéramos cambiar el título de las entradas y no el de otros tipos de contenido? Bueno, gracias a la capacidad de los ganchos para pasar variables a sus funciones de llamadas de retorno, ¡podemos hacerlo!

Echa un vistazo a continuación a una versión modificada de este código:

12345678910111213141516171819202122

/** * Altera el texto de introduce el título aquí. * en el editor clásico de WordPress. * * @param  string $title La cadena de texto actual. * @return string        La cadena de texto modificada. */function ayudawp_title_here( $title, $post ) { // si el contenido no es ‘post’ entrada. if ( ‘post’ !== get_post_type( $post ) ) { // se muestra el marcador original. return $title’ } // aquí se define una cadena nueva para el marcador si el tipo de contenido es ‘post’ entrada. $title = __( ‘Pon aquí el título de tu artículo’, ‘text-domain’ ); // devuelve el título al gancho. return $title;}add_action( ‘enter_title_here’, ‘ayudawp_title_here’, 10, 2 );

En el código anterior hemos hecho algunos pequeños cambios.

En primer lugar, el filtro enter_title_here pasa el objeto actual del mensaje a cualquier llamada de retorno, así como la cadena de título como un segundo arg.

Por lo tanto, cuando llamé a add_action dejé la prioridad en 10, pero añadí otro arg después de eso, un número 2. Esto indica que se pasarán 2 parámetros a la llamada de retorno adjunta, siendo el segundo el objeto post como $post.

Luego busco el tipo de contenido del contenido actual usando get_post_type y paso el objeto del tipo de contenido actual a esa función.

Si el tipo de contenido actual no es una entrada, simplemente devuelvo la cadena de marcador de posición original sin modificar y si el tipo de contenido es una entrada, hacemos nuestro cambio a la cadena de marcador de posición antes de devolverlo.

Importante: El número de variables que estés pasando a tu función de llamada de retorno debe ser declarado como el argumento final en add_filter o add_action.

Puedes encontrar qué variables están disponibles para tus callbacks, ya sea viendo la página para desarrolladores de wordpress.org sobre ganchos (enlace al final de este artículo), o puedes ver dónde se llama el gancho en el código fuente y ver qué variables están disponibles.

Si miramos como ejemplo el widget de nube de etiquetas, puedes ver que en el núcleo de WordPress, el filtro está definido como:

123456789

apply_filters( ‘widget_tag_cloud_args’, array( ‘taxonomy’   => $current_taxonomy, ‘echo’       => false, ‘show_count’ => $show_count, ), $instance);

Este filtro pone a disposición 2 argumentos para las llamadas de retorno. Que son la serie de args (incluyendo taxonomía, eco y mostrar el contador) y la variable de instancia.

Con un filtro, es siempre la primera variable la que se pasa a nuestra llamada de retorno la que debe ser devuelta.

CÓMO USAR GANCHOS PARA ESCRIBIR TU PROPIO CÓDIGO

Los ganchos no son algo que sólo se usa en el núcleo de WordPress o en los plugins de otros.

Tú puedes, y yo diría que deberías, usar ganchos en tu propio código.

Cuando digo usar ganchos me refiero a hacer tu propio código extensible proporcionando ganchos para que otros desarrolladores (¡lo que te incluye a ti por supuesto!) modifiquen tu código de una manera extensible y segura.

¿Dónde debería insertar ganchos?

Cada plugin o tema es diferente y por lo tanto no hay reglas estrictas para definirlo. Sin embargo, estos son algunos de los escenarios que creo que son buenos candidatos para añadir ganchos.

Configuración de arrays

A menudo en nuestro código, usamos arrays para pasar datos a funciones.

Un ejemplo muy simple de esto es cuando estamos usando la clase WP_Query para consultar algunos datos en WordPress.

Pasamos un array a la clase de los parámetros de consulta. Un cambio potencial que podrías hacer a tu código es pasar esta matriz a través de un filtro. Esto permite a otros desarrolladores cambiar esos argumentos de consulta.

Por ejemplo, es posible que a menudo estemos escribiendo algo como esto:

1234567

// ejecuta una query de las últimas 10 tareas.$jobs = new WP_Query( array( ‘posts_per_page’ => 10, ‘post_type       => ‘ayudawp_job’, ));

Podríamos hacer esto mucho mejor usando un filtro, como este:

12345678910

// ejecuta una query de las últimas 10 tareas.$jobs = new WP_Query( apply_filters( ‘ayudawp_job_query_args’, array( ‘posts_per_page’ => 10, ‘post_type       => ‘ayudawp_job’, ) ));

Ahora un desarrollador puede cambiar fácilmente esos argumentos de consulta.

Puede ser que tenga ganas de mostrar sólo las últimas 5 entradas, lo que podría hacer usando este código, colocado por ejemplo en su archivo functions.php del tema o en un plugin:

12345678910111213141516

/** * Cambia la consulta de tareas para mostrar solo 5 entradas por página. * * @param  array $args Los argumentos de consulta actuales. * @return array       Los argumentos de consulta modificados. */function ayudawp_alter_job_query_args( $args ) { // cambia el número de entradas por página a 5. $args[‘posts_per_page’] = 5; // devuelve los argumentos. return $args; }add_filter( ‘ayudawp_job_query_args’, ‘ayudawp_alter_job_query_args’ );

Retornos de función

Otro lugar donde mola añadir ganchos, normalmente en forma de filtro, es para retornos de función.

En lugar de simplemente devolver una cadena, un valor o un array en la función, devuélvela ejecutándola primero a través de un filtro, e incluso pasando los datos relevantes a la llamada de retorno, como un objeto post para que un desarrollador pueda cambiar el valor de retorno si es necesario.

Aquí tienes un posible ejemplo:

123456789

** * Obtiene el nombre de usuario de un feed configurado * en la página de ajustes. * * @return cadena del nombre de usuario del feed o vacío si no está configurado. */function ayudawp_get_username() { return apply_filters( ‘ayudawp_get_username’, get_option( ‘ayudawp_username’ ) );}

Dar salida a cosas en un plugin o tema

Con esto me refiero a cuando, por ejemplo, estés generando HMTL o contenido en un archivo de plantilla.

Es fácil hacer la lógica en el archivo de plantilla y luego generar el HTML necesario para procesar la vista.

Sin embargo, en lugar de hacer esto, a menudo lo mejor es que simplemente añadas una acción a tu archivo de plantilla.

Supongamos que tienes un plugin que está dando salida a una tarea dentro de un loop estándar de WordPress desde una llamada WP_Query.

Puede resultar tentador dar salida al título, contenido, etc. de la entrada dentro de ese loop. Sin embargo, en su lugar yo sugeriría simplemente añadir un gancho dentro de esta manera:

1	do_action( ‘ayudawp_job_output’, $post );

Puedes ver que hemos pasado el objeto de la entrada actual al gancho para que un desarrollador pueda acceder a esa información en cualquier llamada de retorno.

A continuación, puedes añadir tu propia función de llamada de retorno para hacer lo que normalmente habrías hecho directamente en ese archivo de plantilla.

El beneficio de hacerlo de esta manera es que los desarrolladores pueden eliminar su código y añadir el suyo propio.

¿HAY ALGÚN GANCHO PARA ESO?

Ahora sabemos que podemos usar todos los ganchos de WordPress a nuestro favor, pero ¿cómo sabemos si existe un gancho que puedas usar para algo específico?

Hay algunas maneras de encontrar los ganchos que están disponibles en WordPress.

Lee el código

Creo que la mejor manera de saber si hay un gancho disponible para el trabajo que necesitas es leer el código fuente. WordPress es de código abierto y por lo tanto todos podemos ver el código fuente disponible.

Para ello, busco dónde se está ejecutando el código y luego hago una búsqueda de apply_filters y/o do_action en ese archivo. Así fue como encontré el filtro de args de widgets en el ejemplo anterior.

Recursos online

Hay algunos recursos online que nos pueden ayudar con esto.

• El primero, y más obvio, supongo que en el Codex de WordPress, o lo que ahora se conoce como documentos para desarrolladores.
• También está la página de referencia de la API de acciones y la página de referencia de la API de filtros que describe muchos pero no todos los ganchos disponibles.
• Además de estos, también está el índice de ganchos y la API de WordPress, que es una web cuyo objetivo es documentar todos los ganchos en WordPress.

RESUMIENDO

Si hay algo que deberías aprender en profundidad como desarrollador PHP de WordPress, creo que es el sistema de ganchos de WordPress (¡quizás después de Javascript!), ya que realmente te abrirá las puertas a desarrollo de soluciones más personalizadas.

Espero que este artículo te haya ayudado a entender mejor cómo funcionan los ganchos de WordPress, cómo puedes usarlos para alterar su comportamiento sin cambiar nada del código base.

Además, espero que tengas o puedas ganarte la confianza suficiente como para usar ganchos en tus propios temas y plugins para ayudar a otros desarrolladores que los utilicen.