Aproveche el poder de los ganchos de WordPress: explicación de las acciones y los filtros

Como cualquier CMS, WordPress no siempre satisfará todas sus necesidades desde el primer momento. Dado que es de código abierto, puede piratearlo para que se ajuste a las necesidades de su negocio, pero en su lugar, puede usar los ganchos de WordPress para lograr sus objetivos. Construir con ganchos es una estrategia ganadora que libera a los desarrolladores de WordPress para construir casi cualquier característica imaginable del sitio web.

Ganchos de WordPress: acciones y filtros

Los ganchos de WordPress no son solo poderosas herramientas de personalización, son la forma en que los componentes de WordPress interactúan entre sí. Las funciones enlazadas administran muchas de las tareas rutinarias que consideramos parte integral de WordPress, como agregar estilos o scripts a una página, o rodear el texto del pie de página con elementos HTML. Una búsqueda en el código base de WordPress Core revela miles de ganchos en más de 700 ubicaciones. Los temas y complementos de WordPress contienen aún más ganchos.

Antes de saltar a los ganchos y explorar la diferencia entre los ganchos de acción y los ganchos de filtro, comprendamos dónde encajan dentro de la arquitectura de WordPress.

Infraestructura de WordPress

Los elementos modulares de WordPress se integran fácilmente entre sí, por lo que podemos mezclarlos, unirlos y combinarlos fácilmente:

1. Núcleo de WordPress: estos son los archivos necesarios para que WordPress funcione. WordPress Core proporciona una arquitectura generalizada, el panel de administración de WP, consultas de bases de datos, seguridad y más. WordPress Core está escrito en PHP y utiliza una base de datos MySQL.
2. Tema (o tema principal): un tema define el diseño básico y el diseño de un sitio web. Desarrollado por archivos PHP, HTML, JavaScript y CSS, un tema funciona leyendo la base de datos MySQL de WordPress para generar el código HTML que se representa en un navegador. Los ganchos en un tema pueden agregar hojas de estilo, scripts, fuentes o tipos de publicaciones personalizadas, por ejemplo.
3. Tema secundario: creamos temas secundarios nosotros mismos para afinar el diseño y el diseño básicos que proporcionan los temas principales. Los temas secundarios pueden definir hojas de estilo y scripts para modificar funciones heredadas o agregar o eliminar tipos de publicaciones. Las instrucciones del tema secundario siempre reemplazan las del tema principal.
4. Complemento(s): para ampliar la funcionalidad de back-end de WordPress, podemos elegir entre miles de complementos de terceros. Los ganchos en un complemento podrían, por ejemplo, notificarnos por correo electrónico cuando se publica una publicación u ocultar los comentarios enviados por los usuarios que contienen lenguaje prohibido.
5. Complemento(s) personalizado(s): cuando un complemento de terceros no satisface completamente las necesidades comerciales, podemos impulsarlo escribiendo un complemento personalizado en PHP. O podemos escribir un nuevo complemento desde cero. En ambos casos, agregaríamos ganchos para ampliar la funcionalidad existente.

Dado que tenemos acceso a la fuente de las cinco capas, ¿por qué se necesitan ganchos en WordPress?

Código de seguridad

Para mantenerse al día con las tecnologías en evolución, los colaboradores de WordPress Core, los temas principales y los complementos lanzan actualizaciones con frecuencia para mitigar las vulnerabilidades de seguridad, corregir errores, resolver incompatibilidades u ofrecer nuevas funciones. Como cualquier consultor con experiencia en emergencias sabe de primera mano, no mantener actualizados los componentes de WordPress puede comprometer o incluso deshabilitar un sitio.

Si modificamos directamente las copias locales de los componentes anteriores de WordPress, nos encontramos con un problema: las actualizaciones sobrescriben nuestras personalizaciones. ¿Cómo podemos evitar esto al personalizar WordPress? A través de ganchos, en el tema secundario y complementos personalizados.

Codificación en el tema de nuestro hijo

Un tema hijo es un espacio seguro donde podemos personalizar la apariencia de nuestro tema instalado. Cualquier código agregado aquí anulará el código comparable en el padre sin el riesgo de que una actualización lo sobrescriba.

Cuando se activa un tema secundario, se vincula a un tema principal desactivado, heredando y exhibiendo las características del principal sin verse afectado por las actualizaciones del principal. Para no caer en la tentación de modificar un tema, las mejores prácticas sugieren que se active un tema secundario como parte de nuestra configuración.

Escribir complementos personalizados

Cuando se activa un complemento, su archivo functions.php se ejecuta con cada llamada en el servidor. WordPress, a su vez, carga y clasifica los ganchos de todos los complementos activos según su prioridad y los ejecuta secuencialmente. Para ampliar la funcionalidad de un complemento de terceros, podemos escribir nuestro propio complemento personalizado de WordPress.

Dónde colocar nuestros ganchos en WordPress

Preparación previa a la inmersión: definiciones

Para evitar confundir términos, nos ceñiremos a esta terminología:

• Un gancho es un punto dulce en WordPress donde las funciones se registran para ejecutarse. Podemos conectar nuestras funciones a uno de los muchos ganchos en WordPress y sus componentes o crear los nuestros propios.
  • Un gancho de acción ejecuta acciones.
  • Un gancho de filtro ejecuta filtros.
• Una función enganchada es una función de devolución de llamada de PHP personalizada que hemos "enganchado" en una ubicación de enlace de WordPress. El tipo a usar depende de si el gancho está destinado a permitir cambios fuera de la función, por ejemplo, agregar directamente a la salida de la página web, modificar una base de datos o enviar un correo electrónico. Estos se conocen como efectos secundarios .
  • Un filtro (o función de filtro ) debe evitar los efectos secundarios trabajando solo y luego devolviendo una copia modificada de los datos que se le pasan.
  • Una acción (o función de acción ), por el contrario, está destinada a causar efectos secundarios. No tiene valor de retorno.

Con estas distinciones en mente, podemos comenzar nuestra exploración de los anzuelos.

Abstracción y código limpio

Cuando se incorpora una acción o filtro a un hook, según sea necesario, cumplimos con los objetivos de escribir una sola función por tarea y de evitar la duplicidad de código dentro de un proyecto. Por ejemplo, digamos que queremos agregar la misma hoja de estilo a tres plantillas de página (archivo, página única y publicación personalizada) en nuestro tema. En lugar de anular cada plantilla en el elemento principal, luego recrear cada una en nuestro tema secundario y luego agregar hojas de estilo a las secciones de encabezado individuales, podemos escribir código en una sola función y adjuntarlo con el wp_head .

Nomenclatura reflexiva

Evite conflictos de manera proactiva nombrando un tema secundario o complementos personalizados de forma única. Tener ganchos con el mismo nombre en un solo sitio es una receta para el comportamiento no deseado del código. Las mejores prácticas prescriben que comencemos el nombre de nuestro gancho con un prefijo único y breve (por ejemplo, las iniciales del autor, del proyecto o de la empresa), seguido de un nombre descriptivo del gancho. Por ejemplo, usando el patrón "iniciales del proyecto más nombre de enlace", para el Fabuloso Complemento de Tahir del proyecto, podríamos nombrar nuestros tfp-upload-document o tfp-create-post-news .

Desarrollo y depuración simultáneos

Un solo gancho puede desencadenar más de una acción o filtro. Por ejemplo, podríamos escribir una página web que contenga varios scripts, todos los cuales usan el enlace de acción wp_head para imprimir HTML (por ejemplo, una sección <style> o <script> ) dentro de la sección <head> en la parte frontal de la página.

Por lo tanto, varios desarrolladores de complementos pueden avanzar en múltiples objetivos en paralelo en un solo complemento, o dividir el complemento en múltiples complementos individuales más simples. Si una función no funciona correctamente, podemos investigar y depurar directamente su función enganchada sin tener que buscar en todo el proyecto.

Comportamiento

Una acción ejecuta código cuando ocurre un evento en WordPress. Las acciones pueden realizar operaciones como:

• Creando datos.
• Lectura de datos.
• Modificación de datos.
• Eliminación de datos.
• Registro de los permisos de los usuarios registrados.
• Seguimiento de ubicaciones y almacenamiento en la base de datos.

Los ejemplos de eventos en los que se pueden desencadenar acciones incluyen:

• init , después de que se cargue WordPress pero antes de enviar encabezados a la secuencia de salida.
• save_post , cuando se ha guardado una publicación.
• wp_create_nav_menu , justo después de que se haya creado correctamente un menú de navegación.

Una acción puede interactuar con una API para transmitir datos (p. ej., un enlace a una publicación en las redes sociales), pero no devolverá datos al enlace de llamada.

Digamos que nos gustaría automatizar el intercambio de todas las publicaciones nuevas en nuestro sitio a través de las redes sociales. Comience por buscar en la documentación de WordPress un gancho que se pueda activar cada vez que se publique una publicación.

No hay atajos para encontrar nuestro anzuelo: aprenderíamos a través de la experiencia o analizaríamos minuciosamente las acciones enumeradas para encontrar posibles candidatos. Podríamos considerar save_post como un candidato, pero descartarlo rápidamente ya que se activaría varias veces durante una sola sesión de edición. Una mejor opción es transition_post_status , que se activa solo cuando se cambia el estado de una publicación (por ejemplo, de draft a publish , de publish a trash ).

Iremos con transition_post_status pero también refinaremos nuestra acción para que se ejecute solo cuando el estado de nuestra publicación cambie a publish . Además, siguiendo la documentación oficial y las API de las diversas plataformas de redes sociales, podemos integrar y publicar el contenido de nuestra publicación, junto con una imagen destacada:

 <?php function publish_post_on_social_media ( $new_status = NULL, $old_status = NULL, $post_ID = NULL ) { if ( 'publish' == $new_status && 'publish' != $old_status ) { // build the logic to share on social media } } add_action( 'transition_post_status', 'publish_post_on_social_media', 10, 3 ); ?>

Ahora que sabemos cómo usar ganchos de acción, hay uno que es particularmente útil, especialmente cuando se trata de CSS.

Designación de prioridades con wp_enqueue_scripts

Digamos que queremos agregar la hoja de estilo de nuestro tema secundario en último lugar, después de que todas las demás se hayan cargado, para garantizar que las clases de nuestro tema secundario anulen cualquier clase con el mismo nombre que se origine en otro lugar.

WordPress carga las hojas de estilo en un orden predeterminado:

1. tema principal
2. tema infantil
3. Cualquier complemento

En esta construcción:

 add_action( string $hook_name, callable $callback, int $priority = 10, int $accepted_args = 1)

…el valor de priority de la acción añadida determina su orden de ejecución:

• El valor de priority predeterminado para wp_enqueue_scripts (o cualquier acción) es "10".
• Una función se ejecuta antes si restablecemos su priority a un número más bajo.
• Una función se ejecuta más tarde si restablecemos su priority a un número más alto.

Para cargar la hoja de estilo de nuestro tema secundario en último lugar, use wp_enqueue_scripts , una acción que comúnmente usan los temas y complementos de WordPress. Solo necesitamos cambiar la prioridad de la acción wp_enqueue_scripts de nuestro tema hijo a un número mayor que el predeterminado de "10", digamos "99":

 add_action( 'wp_enqueue_scripts', 'child_theme_styles', 99 );

En general, usamos acciones cuando no estamos buscando valores de retorno. Para devolver datos al gancho de llamada, debemos mirar los filtros.

filtros

Un filtro nos permite modificar los datos antes de que se procesen para mostrarlos en un navegador. Con este fin, un filtro acepta variables, modifica los valores pasados ​​y devuelve datos para su posterior procesamiento.

WordPress busca y ejecuta todos los filtros registrados antes de preparar el contenido para los navegadores. De esta forma, podemos manipular los datos antes de enviarlos al navegador o base de datos, según corresponda.

Uno de mis clientes personaliza los productos que vende imprimiéndolos con imágenes que proporcionan los clientes. Este cliente utiliza el complemento WooCommerce para administrar el comercio electrónico. WooCommerce no admite esta funcionalidad de fábrica. Por lo tanto, agregué dos bits de código a functions.php de mi cliente:

1. woocommerce_checkout_cart_item_quantity , que figura en la documentación de WooCommerce, es un gancho de filtro que permite a los clientes agregar elementos externos a sus carritos antes de pagar.
2. my_customer_image_data_in_cart es un filtro que escribiremos nosotros mismos y usaremos para activar woocommerce_checkout_cart_item_quantity siempre que WooCommerce prepare un carrito para mostrarlo.

Usando la siguiente plantilla, podemos agregar agregar nuestro filtro y modificar el comportamiento predeterminado del carrito:

 add_filter( 'woocommerce_checkout_cart_item_quantity', 'my_customer_image_data_in_cart', 1, 3 ); function my_customer_image_data_in_cart( $html, $cart_item, $cart_item_key ) { if ( !empty( $cart_item['images_data'] ) ) { // Store image // Get image URL // Modify $html } return $html; }

Agregamos filtros de la misma manera que agregamos acciones. Los filtros funcionan de manera similar a las acciones, incluida la forma en que se procesan las prioridades. La principal diferencia entre los filtros y las acciones es que una acción no devolverá datos al enlace de llamada, pero un filtro sí.

Ganchos de acción y ganchos de filtro personalizados

Escribir ganchos de acción personalizados no amplía Wordpress Core, sino que simplemente crea nuevos puntos de activación dentro de nuestro propio código.

Creación de ganchos de acción personalizados

Agregar un enlace personalizado en nuestro tema o complemento permite que otros desarrolladores amplíen la funcionalidad sin modificar nuestra base de código. Para agregar un gancho personalizado, use la misma técnica que usa la base de código principal de WordPress: en nuestro punto de activación deseado, simplemente llamamos a do_action con el nombre de nuestro nuevo gancho, opcionalmente agregando tantos argumentos como nuestras devoluciones de llamada puedan resultar útiles:

 do_action( 'myorg_hello_action', $arg1, $arg2 );

Este código simplemente ejecuta cualquier función de devolución de llamada que se haya conectado a nuestro gancho personalizado. Tenga en cuenta que el espacio de nombres es global, por lo que, como se sugirió anteriormente, sería una buena idea anteponer nuestros nombres de enlace personalizados con una forma abreviada del nombre de nuestra organización (y posiblemente también de nuestro proyecto), de ahí el myorg_ aquí.

Ahora que hemos definido myorg_hello_action , está disponible para que los desarrolladores se conecten exactamente de la misma manera que cubrimos anteriormente para enlaces integrados: defina una función, luego llame a add_action() .

A menos que queramos usar un nuevo enlace puramente internamente (después de todo, es una forma útil de estructurar nuestro código), tendremos que comunicar su disponibilidad en sentido descendente, a otros miembros de nuestro equipo o a usuarios externos de nuestro complemento, a través de una documentación clara. .

Creación de ganchos de filtro personalizados

El patrón de WordPress para los ganchos de filtro personalizados es el mismo que el de los ganchos de acción, excepto que llamamos apply_filters() en lugar de do_action() .

Veamos un ejemplo más concreto esta vez. Supongamos que nuestro complemento crea un menú de barra lateral, que normalmente consta de cuatro elementos. Agregaremos un enlace de filtro personalizado para que nosotros (y los desarrolladores posteriores) podamos modificar esa lista de elementos en otros lugares:

 // Text labels of sidebar menu $sidebar_menu = array( "Page One", "Page Two", "Page Three", "Page Four" ); $sidebar_menu = apply_filters( 'myorg_sidebar_menu', $sidebar_menu );

Eso es todo: nuestro enlace de filtro personalizado myorg_sidebar_menu ahora está listo para usar en un complemento que puede cargarse más tarde o en otro lugar de este. Esto permite que cualquiera que escriba código descendente pueda personalizar nuestra barra lateral.

Nosotros u otros desarrolladores seguiremos el mismo patrón cuando usemos un gancho integrado de WordPress. En otras palabras, comenzaremos definiendo algunas funciones de devolución de llamada que devuelven una versión modificada de los datos que se pasan:

 function lowercase_sidebar_menu( $menu ) { $menu = array_map( 'strtolower', $menu ); return $menu; } function add_donate_item( $menu ) { $menu = array_push( $menu, 'Donate' ); return $menu; }

Al igual que con nuestros ejemplos anteriores, ahora estamos listos para conectar nuestras funciones de devolución de llamada de filtro a nuestro enlace personalizado:

 add_filter( 'myorg_sidebar_menu', 'add_donate_item', 100 ); add_filter( 'myorg_sidebar_menu', 'lowercase_sidebar_menu' );

Con eso, hemos enganchado nuestras dos funciones de devolución de llamada de ejemplo en nuestro gancho de filtro personalizado. Ambos ahora modifican el contenido original de $the_sidebar_menu . Debido a que le dimos un valor de priority más alto a add_donate_item , se ejecuta más tarde, después de que se ejecuta lowercase_sidebar_menu .

Los desarrolladores intermedios siempre tienen la libertad de conectar más funciones de devolución de llamada a myorg_sidebar_menu . Mientras lo hacen, pueden usar el parámetro de priority para hacer que sus ganchos se ejecuten antes, después o entre nuestras dos funciones de devolución de llamada de ejemplo.

El cielo es el límite con acciones y filtros

Con acciones, filtros y ganchos, la funcionalidad de WordPress puede crecer a pasos agigantados. Podemos desarrollar funciones personalizadas para nuestro sitio, dejando nuestras propias contribuciones tan extensibles como WordPress. Los ganchos nos permiten adherirnos a la seguridad y las mejores prácticas a medida que llevamos nuestro sitio de WordPress al siguiente nivel.

El blog de ingeniería de Toptal extiende su gratitud a Fahad Murtaza por su experiencia, pruebas beta y revisión técnica de este artículo.