Los ganchos de WordPress son una de las herramientas más importantes para tener en el arsenal de un desarrollador de WordPress. Son la base del desarrollo de plugins y temas de WordPress. Puedes usar los muchos ganchos incorporados de WordPress para «engancharte» al núcleo de WordPress con tu código personalizado y hacer o modificar algo.

Hay dos tipos de ganchos de WordPress: Acciones y Filtros. Los ganchos son tan comunes que hasta el núcleo de WordPress los usa extensamente por sí mismo. WordPress también incluye una forma de definir tus propios ganchos personalizados para que otros desarrolladores puedan engancharse a tu código.

Aprender cómo funcionan las acciones, los filtros y los ganchos personalizados es esencial para dominar el desarrollo de WordPress.

La primera mitad de este artículo cubre los fundamentos de los ganchos de WordPress y explica cómo funcionan con múltiples ejemplos. En la segunda mitad, aprenderás cómo puedes usar los ganchos para personalizar WordPress, crear tus propios ganchos personalizados y usarlos para construir tus propios plugins extensibles.

¿Suena emocionante? ¡Vamos a sumergirnos!

¿Qué son los ganchos de WordPress?

Una página de WordPress está ensamblada por toneladas de funciones y consultas a bases de datos. El núcleo de WordPress, los plugins y el tema trabajan juntos para producir los elementos de la página como texto, imágenes, scripts y estilos. Una vez ensamblados, el navegador los pone todos juntos y muestra la página.

Los ganchos de WordPress te permiten «engancharte» a este proceso de construcción en ciertos puntos y ejecutar tu código personalizado. La función principal de los ganchos es permitirte modificar o añadir características a WordPress sin tocar los archivos centrales.

Los ganchos te ayudarán a extender WordPress con tu propio código

Los ganchos te ayudarán a extender WordPress con tu propio código

La API del plugin de WordPress potencia la funcionalidad de los ganchos de WordPress. Los ganchos se utilizan llamando a ciertas funciones de WordPress llamadas Funciones de Gancho en instancias específicas durante el tiempo de ejecución de WordPress.

Usando las funciones de gancho, puedes agrupar tu código personalizado dentro de una función de callback y registrarlo con cualquier gancho. Una vez registrado, esta callback se ejecutará dondequiera que esté el gancho, permitiéndote aumentar o reemplazar las funciones predeterminadas de WordPress.

La posición del gancho en el proceso de ejecución del código es un factor importante. Aprenderás más sobre su importancia en las próximas secciones.

Engánchate a #webdev con esta guía de ganchos de WordPress. ⚡️Click to Tweet

Dos tipos de ganchos de WordPress: Acciones y Filtros

WordPress incluye dos tipos de ganchos llamados Acciones y Filtros. Las Acciones te permiten hacer algo en ciertos puntos predefinidos en el tiempo de ejecución de WordPress, mientras que los Filtros te permiten modificar cualquier dato procesado por WordPress y devolverlo.

Las acciones se definen en el código de WordPress como:

do_action( 'action_name', [optional_arguments] );

La cadena action_name es el nombre de la acción. Puedes especificar la variable [optional_arguments] para pasar argumentos adicionales a la función de callback. Si no se especifica este campo, entonces su valor por defecto estará vacío.

Ejemplo: La acción do_action( 'wp_head' ) puede ser enganchada para ejecutar código personalizado cada vez que WordPress procesa el encabezado del sitio. Esta acción no tiene ningún otro argumento.

Los filtros están definidos en el código de WordPress como:

apply_filters( 'filter_name', 'value_to_be_filtered', [optional_arguments] );

La cadena filter_name es el nombre del filtro, la variable value_to_be _filtered es el valor que debe ser filtrado y devuelto, y la variable [optional_arguments] puede pasar argumentos adicionales, al igual que con las acciones.

Ejemplo: El filtro apply_filters( 'admin_footer_text' , string $text ) puede ser enganchado para modificar el texto que se muestra en el pie de página del admin. A partir de WordPress 5.4, su valor predeterminado mostrará la frase Thank you for creating with WordPress. en el pie del área de administración.

Aprenderás a engancharte a las acciones y filtros más tarde con muchos ejemplos del núcleo de WordPress.

Una vez enganchado, puedes dirigir tu código para hacer o personalizar algo en tu sitio. Por ejemplo, puedes utilizar ganchos para enviar un correo electrónico automático después de publicar un mensaje, o cargar hojas de estilo personalizadas para cambiar la apariencia de tu sitio.

Los ganchos de WordPress te ayudan a interactuar o modificar tu sitio web

Los ganchos de WordPress te ayudan a interactuar o modificar tu sitio web

La forma más simple de entender los ganchos es imaginar que tu sitio web de WordPress está construyendo una casa.

Los ganchos son similares a usar una grúa para mover objetos de construcción de un lado a otro. Los artículos que se transfieren son las funciones de callback que incluyen tu código personalizado. Estos artículos (o funciones) pueden ayudarte a construir o modificar la casa.

Ejemplo de enganche en la acción

Ejemplo de enganche en la acción «wp_head» en WordPress

Las funciones de callback pueden ser funciones regulares de PHP, funciones predeterminadas de WordPress o funciones personalizadas definidas por tí.

Sólo podemos llevar ciertos artículos en portadores específicos unidos a ganchos particulares. Por lo tanto, las acciones sólo pueden ser enganchadas con las funciones de acción. Del mismo modo, los filtros sólo pueden ser enganchados con Funciones de Filtro.

Mientras que es tedioso cambiar los ganchos y los portadores en una grúa, WordPress lo hace súper fácil al incluir más de 2.200 tipos de ganchos predeterminados.

WordPress 5.1 tiene más de 2200 ganchos nativos

WordPress 5.1 tiene más de 2200 ganchos nativos (Fuente: Adam Brown)

Puedes encontrar ganchos repartidos por el núcleo de WordPress, lo que te permite acceder a la posición exacta en la que quieres engancharte y ejecutar tu código personalizado.

Los ganchos de WordPress te permiten 'engancharte' al proceso de construcción de la página... y te dan más control sobre lo que creas.⚡️Click to Tweet

Ganchos vs Acciones vs Filtros

Según el manual de plugins de WordPress:

«Los ganchos son una forma de que una pieza de código interactúe/modifique otra pieza de código… Hay dos tipos de ganchos: Acciones y Filtros.

Hay una incoherencia generalizada en la forma en que se utilizan los términos Gancho, Acción y Filtro. Algunos tutoriales y guías los mezclan con las funciones asociadas a ellos. Una de las principales razones por las que existe esta confusión es por la compleja naturaleza del funcionamiento de los ganchos.

Incluso si miras cuidadosamente dentro del núcleo de WordPress, verás que no hay mucha diferencia entre añadir acciones y filtros. Aquí está el código fuente de la función add_action() del archivo wp-includes/plugin.php:

function add_action( $tag, $function_to_add, $priority = 10, $accepted_args = 1 ) {      
    return add_filter( $tag, $function_to_add, $priority, $accepted_args );
}

La función add_action() sólo llama a la función add_filter() y devuelve su valor. ¿Por qué? Porque ambas funcionan fundamentalmente de la misma manera, excepto por una diferencia.

La función apply_filters() devuelve un valor que puede cambiar los tipos de datos existentes, mientras que la función do_action() no devuelve nada (valor NULL en PHP).

Si todavía estás confundido, no te preocupes. Una vez que termines la primera mitad de este artículo, todo estará claro. Nos ceñiremos a la terminología oficial del Codex de WordPress ya que es clara, precisa y universal.

Por ahora, familiarízate con la rutina del gancho que se muestra a continuación.

La rutina del gancho

La rutina del gancho: Ganchos, funciones de gancho y funciones de callback

Vamos a desglosar las diferencias entre Acciones y Ganchos.

Ganchos de WordPress
Acciones Filtros
Las acciones se utilizan para ejecutar funciones personalizadas en un punto específico durante la ejecución de WordPress Core. Los filtros se utilizan para modificar o personalizar los datos utilizados por otras funciones.
Las acciones son definidas/creadas por la función do_action( 'action_name' ) en el código de WordPress. Los filtros son definidos/creados por la función apply_filters( 'filter_name', 'valu_to_be_filtered' ) en el código de WordPress.
Las acciones también se llaman ganchos de acción. Los filtros también se llaman ganchos de filtro.
Las acciones sólo se pueden enganchar con las funciones de acción. Por ejemplo, add_action(), remove_action(). Los filtros sólo se pueden enganchar con las funciones de filtro. Por ejemplo, add_filter(), remove_filter().
Las funciones de acción no necesitan pasar ningún argumento a sus funciones de callback. Las funciones de filtro necesitan pasar al menos un argumento a sus funciones de callback.
Las funciones de acción pueden realizar cualquier tipo de tarea, incluyendo cambiar el comportamiento de cómo funciona WordPress. Las funciones de los filtros sólo existen para modificar los datos que les pasan los filtros.
Las funciones de acción no deberían return nada. Sin embargo, pueden hacer echo salida o interactuar con la base de datos. Las funciones del filtro deben return devolver sus cambios como salida. Aunque una función de filtro no cambie nada, debe return la entrada no modificada.
Las acciones pueden ejecutar casi cualquier cosa, siempre que el código sea válido. Los filtros deben funcionar de manera aislada, para que no tengan efectos secundarios no deseados.
Resumen: Una acción interrumpe el proceso regular de ejecución del código para hacer algo con la información que recibe, pero no devuelve nada, y luego sale. Resumen: Un filtro modifica la información que recibe, la devuelve a la función de gancho de llamada, y otras funciones pueden usar el valor que devuelve.

A veces, se puede utilizar una acción o un filtro para lograr el mismo objetivo. Por ejemplo, si quieres modificar el texto de un post, puedes registrar una función de callback con la acción publish_post y cambiar el contenido del post cuando se guarda en la base de datos.

// define the callback function to change the text
function change_text_callback() { 
    // add the code to change text here
}

// hook in to the 'publish_post' action with the add_action() function
add_action( 'publish_post', 'change_text_callback' );

O puedes registrar otra función de callback con e content_filter para modificar el contenido del mensaje antes de que se muestre en el navegador.

// define the callback function to modify the text
function change_text_another_callback( $content ) { 
    // add the code to change text here and then return it 
    return $filtered_content;
}

// hook in to 'the_content' filter with the add_filter() function
add_filter( 'the_content', 'change_text_another_callback');

Dos enfoques diferentes con el mismo resultado. Saber cuándo usar uno sobre el otro es la clave para ser un buen desarrollador de WordPress.

¿Cómo funcionan los ganchos de WordPress?

El ejemplo de la casa era lo suficientemente simple como para entender el funcionamiento básico de los ganchos, pero no capta la complejidad de su funcionamiento. Lo más importante son los conceptos de posición y especificidad del gancho.

Un mejor ejemplo sería imaginar el procesamiento de una página web de WordPress como el montaje de un coche. A diferencia de la fabricación de un coche, que lleva tiempo, el montaje de una página web es casi instantáneo.

Montar una página web es como montar un coche

Montar una página web es como montar un coche

Al igual que un coche se ensambla pieza por pieza en una línea de montaje moderna, una página web de WordPress se ensambla elemento por elemento por el servidor y el cliente.

El núcleo de WordPress es como el motor del coche, el chasis y otros elementos esenciales, que potencian la funcionalidad del «núcleo» del sitio web.

Puedes tener un sitio web funcional sólo con el núcleo de WordPress, pero ¿dónde está la diversión en eso? Necesitas agregar características emocionantes al sitio. Ahí es donde intervienen los plugins y temas de WordPress, los cuales usan ganchos extensamente.

En el ejemplo anterior, cada estación numerada es como un gancho dentro del núcleo de WordPress. Hay dos tipos de estaciones, como acciones y filtros. Cada estación incluye un tipo específico de ranura que sólo acepta ciertas herramientas, como las funciones de acción y las funciones de filtro.

Todas las estaciones se colocan a intervalos frecuentes para mayor modularidad y eficiencia.

Dependiendo de los requisitos de un puesto concreto, podemos acoplar (o enganchar) la herramienta más apropiada para el trabajo en esa estación concreta. Estas herramientas son como las funciones de callback que se utilizan para interactuar o modificar WordPress.

Algunas herramientas pueden alterar significativamente el funcionamiento del coche, como las llamadas registradas a las acciones. Otras herramientas sólo se utilizan para personalizar el aspecto del coche, como las llamadas registradas a los filtros.

Usar las herramientas correctas en las estaciones correctas es crucial para construir un coche de primera clase. De la misma manera, los ganchos nos ayudan a personalizar WordPress según nuestras necesidades únicas.

Si extiendes esta analogía, los plugins son como añadir útiles funciones de automóvil como airbags, consola de entretenimiento, sistema remoto sin llaves, etc. (como estos para mejorar la funcionalidad de WooCommerce). Los temas son análogos a la personalización de la parte visual del coche, como el diseño general, la pintura, las llantas, etc. (aquí está cómo personalizar el tema de WordPress).

¿Dónde registrar los ganchos y sus funciones?

Hay dos formas recomendadas de añadir ganchos en WordPress:

Para este tutorial, empecemos por crear un plugin. Para ello, crea una nueva carpeta en tu directorio /wp-content/plugins/.

Estoy nombrando a mi plugin salhooks, pero puedes nombrarlo como quieras. Según las directrices de WordPress, debes crear un archivo PHP con el mismo nombre (salhooks.php) dentro del directorio de tu plugin.

Añade los siguientes campos de encabezado a tu archivo de plugin para registrarlo con WordPress. Puedes obtener más información sobre los requisitos de encabezado de los plugins en el Codex de WordPress.

<?php

/*
Plugin Name:  Salhooks
Version    :  1.0
Description:  Demonstrating WordPress Hooks (Actions and Filters) with multiple examples.
Author     :  Salman Ravoof
Author URI :  https://www.salmanravoof.com/
License    :  GPLv2 or later
License URI:  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:  salhooks
*/

//=================================================
// Security: Abort if this file is called directly
//=================================================
if ( !defined('ABSPATH') ) { 
    die;
}

Guarda este archivo y luego activa el plugin en tu panel de control de WordPress. Usaré este plugin dentro de una instalación local de WordPress para demostrar cómo funcionan los ganchos.

Como nota al margen, también puedes editar los archivos de WordPress Core directamente para registrar los ganchos. Sin embargo, no es recomendable ya que todo tu código personalizado será sobrescrito cada vez que actualices WordPress. No deberías añadir ganchos dentro del tema principal por la misma razón.

Usando ganchos de WordPress

Un gancho de WordPress por sí solo no hace nada. Sólo se sienta en el código, esperando que alguna función de gancho lo active. Para hacer uso de un gancho, necesitas llamar al menos a otras 2 funciones.

Primero, tienes que registrar el gancho con una función de gancho y referirte a una función de callback dentro de él. Y luego necesitas definir la función de callback que mencionaste anteriormente en la función de gancho. WordPress ejecutará esta función callback cada vez que el gancho sea disparado.

El orden en el que se definen estas funciones no importa, pero es una buena idea colocarlas muy juntas.

Las acciones y los filtros tienen distintas funciones de gancho. A partir de ahora, nos referiremos a ellas como Funciones de Acción y Funciones de Filtro. Como verás, tienen sus propios requisitos de sintaxis y parámetros.

Enganchar una acción

Las acciones proporcionan una forma de ejecutar tu código personalizado en un punto determinado de la ejecución de WordPress Core, plugins o temas.

La función de acción add_action()

Puedes registrar una función de callback con una acción siguiendo estos pasos:

  1. Define una función de callback con tu código personalizado dentro de ella. Esta función de callback se ejecutará cuando cualquier acción registrada se dispare durante la ejecución del código de WordPress.
  2. Engancha tu función de callback a la acción que quieras con la función add_action(). Según el Codex de WordPress, la función add_action() necesita pasar al menos dos parámetros:
    1. Nombre de la acción a la que se engancha.
    2. Nombre de la función de callback que se ejecutará cuando se active la acción.
  3. La función add_action() también acepta dos parámetros opcionales para establecer la priority y el mumber of arguments. Discutiremos ambos más tarde.

Es una buena práctica nombrar los parámetros de la función de callback lo más cerca posible de los parámetros pasados por la función de gancho.
Veamos un ejemplo de uso de la función add_action().

// define the callback function, the arguments are optional
function example_callback( $arg1, $arg2 ) {
    // make your code do something with the arguments
}

// hook the callback function to the 'example_action'
add_action( 'example_action', 'example_callback', [priority], [no_of_args] );

// 'priority' and 'number of arguments' are optional parameters

Ejemplo de enganche de una acción

WordPress incluye una acción incorporada llamada init que se dispara después de que WordPress ha terminado de cargar y autentificar al usuario, pero antes de que se envíe cualquier encabezado. Muchos plugins usan este gancho como punto de partida para instanciar su código ya que casi todas las principales características de WordPress han terminado de cargarse en el momento en que WordPress ejecuta esta acción.

WordPress tiene una acción similar llamada admin_init. Se dispara mientras la pantalla de administración se está inicializando, mientras que la acción init se dispara sólo después de que WordPress ha terminado de cargar.

Vamos a ejecutar un código personalizado para hacer eco de un simple mensaje durante la ejecución de la acción init. Así es como se hace:

function custom_callback_function(){
    // add your custom code here to do something
    echo 'I will be fired on WordPress initialization';
}
add_action( 'init', 'custom_callback_function' );

Puedes ver el mensaje que se repite en la esquina superior izquierda de mi instalación local de WordPress.

No es tan bonito, pero es un gran comienzo.

No es tan bonito, pero es un gran comienzo.

Encontrar acciones apoyadas por WordPress

WordPress incluye acciones cada vez que hace algo, como que un usuario se conecte o publique un nuevo post. Puedes encontrar una lista completa de todas las acciones ejecutadas por WordPress en la página Referencia de la API/Acción del Plugin.

Hay una acción para casi todos los usos

Hay una acción para casi todos los usos

El Codex ha dividido todas las acciones enumeradas allí en varias categorías y las ha ordenado del primero al último en el orden de ejecución de WordPress.

En la mayoría de los casos, muchas de estas acciones no harán nada ya que nada está enganchado a ellas. Pero si las necesitas, están ahí para que te enganches a ellas.

¿Te sientes un poco abrumado con todas las acciones? Es natural. A medida que adquieras más experiencia y revises el código fuente del núcleo de WordPress, será más fácil encontrar el gancho perfecto para tus necesidades. Sólo realiza una búsqueda del término «do_action» y encontrarás un montón de acciones en las que puedes engancharte.

Parámetros adicionales para add_action()

La función add_action() puede aceptar dos parámetros más: uno para establecer la priorityy el otro para establecer el number of arguments. Aunque son opcionales, si se usan correctamente, pueden ser muy útiles.

Prioridad

El primer parámetro adicional soportado por la función add_action() establece  priority. Este parámetro sólo puede ser un entero positivo. Cuanto menor sea el número de prioridad, antes se ejecutará la función. Su valor predeterminado es 10 si no lo especificas.

Para ver cómo funciona, registremos tres funciones de callback a la acción init, pero cada una con diferentes prioridades.

// priority is set to 9, which is lower than 10, hence it ranks higher
add_action( 'init', 'i_am_high_priority', 9 );

// if no priority is set, the default value of 10 will be used
add_action( 'init', 'i_am_default_priority');

// priority is set to 11, which is higher than 11, hence it ranks lower
add_action( 'init', 'i_am_low_priority', 11 );

En los ejemplos anteriores, la función de callback con el número de menor prioridad se ejecutará primero y la de mayor número se ejecutará en último lugar. Si sus prioridades son las mismas, entonces se ejecutarán en el orden en que se registren.

La prioridad juega un papel importante cuando un solo gancho puede tener registradas múltiples funciones de callback. Para evitar resultados inesperados, puedes establecer una prioridad para cada función de callback, para que se disparen en el orden que desees.

Número de argumentos

Por defecto, cualquier función de callback registrada a través de la función add_action() recibirá sólo un argumento. Sin embargo, a veces puede ser necesario pasar datos adicionales a la función callback.

Por esta razón la función add_action() acepta un parámetro opcional para establecer el número de argumentos.

Un gran ejemplo para mostrar esto es la acción comment_post. Esta acción se ejecuta inmediatamente después de que WordPress añade un comentario a la base de datos. Si no se establece el parámetro de number of arguments, pasará sólo un valor a la función de callback, que en este caso será el comment_ID.

// register the hook with 'priority' and 'number of arguments' parameters
add_action( 'comment_post', 'show_message_function', 10, 3 );

// define the callback function
function show_message_function( $comment_ID, $comment_approved, $commentdata ) {
    // check whether a comment is approved with the second parameter
    if( 1 === $comment_approved ){
        // runs the code only if the comment is approved
    }
}

Si se establece el parámetro de número de argumentos en 3 como en el ejemplo anterior, la función de acción pasará tres valores: comment_ID, comment_approved, y commentdata.

WordPress establece el valor comment_approved en 1 para los comentarios aprobados, en 0 si no están aprobados y en «spam» si el comentario está marcado como tal.

La variable commentdata es una matriz que incluye todos los datos del comentario, como el nombre del autor del comentario, la dirección de correo electrónico, el sitio web y el contenido del propio comentario. Puedes revisar el Codex de WordPress para encontrar todos los pares clave-valor incluidos en la matriz de «commentdata».

Puedes tener tantos argumentos como quieras, pero la función callback y la función add_action() necesitan especificar el mismo número de argumentos.

Pasando parámetros adicionales a la función de callback, puedes hacer más con tu código. Por ejemplo, puedes comprobar si un comentario está aprobado o no y enviar automáticamente el texto del comentario al administrador si está aprobado. No es posible hacerlo sin especificar los argumentos adicionales, ya que la función de callback no tendrá acceso a los datos de comment_content.

Si no quieres establecer la prioridad, pero sólo quieres cambiar el número de argumentos, todavía tienes que establecer una prioridad. Sólo tienes que usar su valor por defecto (es decir, 10).

¿Cómo el núcleo de WordPress utiliza las acciones?

El propio WordPress Core utiliza muchas de sus acciones incorporadas para realizar varias funciones.

Tomemos la acción wp_head por ejemplo. Se dispara cuando WordPress produce la sección de encabezado de las páginas web (el código que va entre <head> y </head> ).

Puedes encontrar la mayoría de las funciones de acción de WordPress Core relacionadas con el gancho wp_head en el archivo wp-includes/default-filters.php. He revisado el código y compilado una lista de todas las funciones add_action() que invocan la acción wp_head.

add_action( 'wp_head', 'rest_output_link_wp_head', 10, 0 );
add_action( 'wp_head', '_wp_render_title_tag', 1 );
add_action( 'wp_head', 'wp_enqueue_scripts', 1 );
add_action( 'wp_head', 'wp_resource_hints', 2 );
add_action( 'wp_head', 'feed_links', 2 );
add_action( 'wp_head', 'feed_links_extra', 3 );
add_action( 'wp_head', 'rsd_link' );
add_action( 'wp_head', 'wlwmanifest_link' );
add_action( 'wp_head', 'adjacent_posts_rel_link_wp_head', 10, 0 );
add_action( 'wp_head', 'locale_stylesheet' );
add_action( 'wp_head', 'noindex', 1 );
add_action( 'wp_head', 'print_emoji_detection_script', 7 );
add_action( 'wp_head', 'wp_print_styles', 8 );
add_action( 'wp_head', 'wp_print_head_scripts', 9 );
add_action( 'wp_head', 'wp_generator' );
add_action( 'wp_head', 'rel_canonical' );
add_action( 'wp_head', 'wp_shortlink_wp_head', 10, 0 );
add_action( 'wp_head', 'wp_custom_css_cb', 101 );
add_action( 'wp_head', 'wp_site_icon', 99 );
add_action( 'wp_head', 'wp_no_robots' );

Son muchas funciones de callback enganchadas a una sola acción. Establecer priorityaquí es crucial para asegurar que las funciones enganchadas más importantes funcionen primero.

En el ejemplo anterior, la carga de los scripts con la función de callback wp_enqueue_scripts() es más importante (prioridad = 1) que la carga de las metaetiquetas del icono del sitio con la función de callback wp_site_icon() (prioridad = 99).

Info

Todas las funciones de callback utilizadas en el ejemplo anterior son funciones de WordPress. También puedes usarlas en cualquiera de tus códigos. Visita la página de referencia de funciones en el Codex de WordPress para más información.

Otras funciones de acción

Mientras que add_action() es la función de acción más utilizada, hay muchas otras que son igualmente útiles. Veamos cómo funcionan todas ellas.

Esta función de acción comprueba si una acción ha sido enganchada. Acepta dos parámetros. El primero es el nombre de la acción. El segundo parámetro es opcional y es el nombre de la función de callback.

has_action( 'action_name', 'function_to_check' );

Si se especifica sólo el primer parámetro, devuelve true si alguna función está enganchada al parámetro action_name.

Pero si también especifica el segundo parámetro, devolverá false si la función de callback especificada no está registrada en la acción mencionada.

Sin embargo, si encuentra la función de callback conectada al gancho de acción, devolverá priority (un entero) establecida para esa función en este gancho de acción.

Ya nos hemos encontrado con esta función de acción antes. WordPress la usa para definir todas sus acciones predeterminadas, permitiendo que otras funciones se enganchen a ellas. Al igual que WordPress, también puede utilizar la función do_action() para crear una nueva acción personalizada especificando un nuevo nombre de acción como parámetro.

do_action( 'action_name', [argument1], [argument2] );

El simple hecho de declarar esta función no hará nada por sí mismo. Pero se sentará en el código, esperando que otras funciones de acción lo activen. Pasar cualquier argumento extra es opcional, pero es importante si quieres que tus funciones de callback las usen.

Esta función de acción es idéntica a do_action(), excepto por una diferencia. Cualquier argumento que se pase por ella debe ser un array. Cuando tienes muchos argumentos que pasar o tus argumentos ya están en un array, esta función es super útil.

// here's an example array
$arguments_array = array( 'arg_1', 'foo', true, 'arg_4' );

do_action_ref_array( 'example_action', $arguments_array );

Ya que las matrices PHP son un mapa ordenado, asegúrate de que los argumentos que pases estén en el orden correcto.

Un ejemplo del uso de esta función de acción es la acción admin_bar_menu. Puede ser enganchada para añadir, manipular o eliminar los diferentes elementos de la barra de administración. Todos los elementos de la barra de administración se definen como elementos de un array.

Si quieres contar el número de veces que se dispara una acción, puede invocar esta función de acción.

did_action( 'action_name' );

Esta función devuelve un valor entero.

La función did_action() es extremadamente útil cuando se quiere ejecutar una función de callback sólo la primera vez que se ejecuta una acción y nunca más.

function example_callback_function() {
    if( did_action( 'example_action' ) === 1 ) {
    // checks if the 'example_action' hook is fired once, and only runs then, and never again!
    }
}
add_action('example_action', 'example_callback_function');

Esta función de acción elimina una función de callback enganchada a la acción especificada. Por ejemplo, puede utilizar esta función para eliminar las funciones predeterminadas de WordPress enganchadas a las acciones incorporadas y sustituirlas por las suyas propias.

remove_action( 'action_name', 'function_to_be_removed', [priority] );

Hay algunos requisitos previos para llamar a la función remove_action():

  1. Los parámetros de function_to_be_removed y prioritydeben ser los mismos que los usados originalmente en la función add_action().
  2. No se puede llamar directamente a la función remove_action(). Necesitas llamarla de otra función.
  3. Si la función de callback se registra de una clase, entonces la eliminación de la misma tiene otros requisitos. Puedes consultar la documentación del Codex de WordPress para obtener más detalles.
  4. No puedes eliminar la función de callback antes de que se registre o después de que se ejecute.

Aquí hay un ejemplo de cómo WooCommerce utiliza esta función de acción para eliminar la miniatura del producto por defecto en la página principal de la tienda.

remove_action( 'woocommerce_before_shop_loop_item_title', 'woocommerce_template_loop_product_thumbnail', 10 );

Esta función de acción elimina todo lo que se engancha a una acción. El parámetro de prioridad es opcional.

remove_all_actions( 'action_name', [priority] );

Recuerda que esta función no puede ser llamada desde la acción de la que deseas desregistrar las funciones de callback. Eso causaría un bucle infinito. Puedes engancharte a una acción que se haya disparado antes para ejecutar esta función sin errores.

Esta función de acción comprueba si la acción especificada se está ejecutando o no. Devuelve un valor booleano (true o false).

// check whether the 'action_name' action is being executed
if ( doing_action( 'action_name' ) ) {
    // execute your code here
}

Puedes dejar el parámetro action_name vacío para comprobar si se está ejecutando alguna acción. Devolverá true cada vez que se dispare cualquier acción.

// check if any action is running and do something
if ( doing_action() ) {
    // the code here is run when any action is fired
}

Acciones Ejemplo 1: Mostrar un mensaje de mantenimiento a los visitantes de tu sitio

A veces, es mejor desconectar la página web y poner una página de mantenimiento. Afortunadamente, WordPress proporciona una manera fácil de hacer eso.

// show a maintenance message for all your site visitors
add_action( 'get_header', 'maintenance_message' );
function maintenance_message() {
    if (current_user_can( 'edit_posts' )) return;
    wp_die( '<h1>Stay Pawsitive!</h1><br>Sorry, we\'re temporarily down for maintenance right meow.' );
}

Desglosemos el código y repasemos cada paso:

Después de guardar el código en mi plugin personalizado, cargué mi instalación local de WordPress en modo de navegación privada. La página de mantenimiento es un éxito!

Mostrando un mensaje de error a los visitantes del sitio

Mostrando un mensaje de error a los visitantes del sitio

El sitio se carga con éxito si estoy conectado y pasa la prueba de capacidad de usuario. Ahora puedes continuar trabajando en la reparación de tu sitio mientras muestra a los visitantes regulares esta página.

Acciones Ejemplo 2: Ocultar los elementos del menú del tablero de mandos a los usuarios que no son administradores

Si tienes un blog de varios autores o administras un sitio para tus clientes, es posible que tengas que ocultar ciertos menús de administración del panel de control de WordPress para los usuarios que no son administradores. Puedes hacerlo enganchándote a la acción admin_menu.

// remove specific dashboard menus for non-admin users
add_action( 'admin_menu', 'hide_admin_menus' );
function hide_admin_menus() {
    if (current_user_can( 'create_users' )) return;
    if (wp_get_current_user()->display_name == "Salman") return; 
    remove_menu_page( 'plugins.php' ); 
    remove_menu_page( 'themes.php' ); 
    remove_menu_page( 'tools.php' ); 
    remove_menu_page( 'users.php' ); 
    remove_menu_page( 'edit.php?post_type=page' ); 
    remove_menu_page( 'options-general.php' );
}

Aquí hay un paseo paso a paso por el fragmento de código de arriba:

Después de guardar el archivo del plugin, aquí hay una instantánea del tablero de WordPress con un administrador conectado.

El panel de administración predeterminado de WordPress

El panel de administración predeterminado de WordPress

Y aquí hay una captura de pantalla del tablero de WordPress con un usuario no administrador conectado.

Hiding the sensitive admin menus to non-admin users using actions

Hiding sensitive admin menu items from non-admin users

Esta solución sólo oculta los elementos del menú de administración especificados para que no aparezcan en el tablero de WordPress. Todos los usuarios pueden seguir accediendo a ellos introduciendo las URL del menú en sus navegadores.

Para deshabilitar el acceso a ciertos roles de usuario a determinados menús, es necesario editar sus capacidades.

Enganchar un filtro

Los filtros proporcionan una forma para que tu código personalizado modifique los datos utilizados por otras funciones de WordPress. A diferencia de las acciones, las funciones enganchadas a los filtros necesitan devolver un valor.

La función add_filter() Filter

Puedes enganchar una función de devolución de llamada a un filtro siguiendo estos pasos:

  1. Define una función de Callback que se ejecutará cuando WordPress dispare el filtro. Las funciones Callback para los filtros deben tener al menos un argumento especificado, ya que todos los filtros pasan al menos un valor a sus funciones Callback.
  2. Registra la función de devolución de llamada a un filtro con la función add_filter(). El filtro se encargará de llamar a la función de devolución de llamada. Según el Codex de WordPress, la función add_filter() necesita pasar al menos dos parámetros:
    • El nombre del filtro al que engancharse.
    • Nombre de la función de llamada que se ejecutará cuando el filtro se dispare.
  3. La función add_filter() también acepta dos parámetros opcionales adicionales para establecer priority y number of arguments. Estos parámetros funcionan de la misma manera que con la función add_action().

Aquí hay un ejemplo de cómo puedes usar la función add_filter() para enganchar una función de devolución de llamada a un filtro.

// define the filter callback function with at least one argument passed
// the number of arguments that you can pass depends on how the filter is defined
function filter_callback_function( $arg1, $arg2 ) {
    // make your code do something with the arguments and return something
    return $something;
}

// now hook the callback function to the 'example_filter'
add_filter( 'example_filter', 'filter_callback_function', [priority], [no_of_args] );

// '10' is the default priority set for the callback function
// and '1' is the default number of arguments passed

Ejemplo de enganche de un filtro

WordPress proporciona un filtro llamado login_message para filtrar el mensaje que se muestra en la página de inicio de sesión encima del formulario de inicio de sesión. El valor devuelto por este filtro puede tener un marcado HTML.

Conectémonos al filtro login_message y modifiquemos el mensaje que aparece en la pantalla de acceso.

// show a custom login message above the login form
function custom_login_message( $message ) {
    if ( empty( $message ) ) {
        return "<h2>Welcome to Let's Develop by Salman Ravoof! Please log in to start learning.</h2>";
    } 
    else {
        return $message;
    }
}
add_filter( 'login_message', 'custom_login_message' );

La declaración if-else en la función de devolución de llamada comprueba si el mensaje de inicio de sesión ya está configurado, principalmente por otro plugin o tema. En tales casos, la función de devolución de llamada devuelve el valor original sin hacer ningún cambio. Esta es una forma de evitar conflictos con otros plugins o temas.

Puedes ver el mensaje que se muestra encima del formulario de acceso en la página de acceso de WordPress.

Mostrando un mensaje personalizado de inicio de sesión encima del formulario de inicio de sesión

Mostrando un mensaje personalizado de inicio de sesión encima del formulario de inicio de sesión

Puedes dar estilo a todos los elementos de la página de inicio de sesión enlazando hojas de estilo personalizadas. Al hacerlo, podrás personalizar completamente tu página de inicio de sesión predeterminada de WordPress.

Aprenderás a cargar hojas de estilo personalizadas usando acciones en la sección «Personalizar la página de inicio de sesión de WordPress con ganchos».

Encontrar filtros con el apoyo de WordPress

En cualquier lugar donde WordPress procese o modifique datos, es casi seguro que se puede encontrar un filtro para engancharlo y cambiarlo. Piensa en los filtros como una interfaz entre la base de datos de WordPress y el navegador.

Puedes encontrar una lista exhaustiva de todos los filtros soportados por WordPress en la página de Referencia de la API/Filtro del Plugin.

WordPress proporciona una variedad de filtros para enganchar en

WordPress proporciona una variedad de filtros para enganchar en

Todos los filtros listados allí se dividen en múltiples categorías y se ordenan de arriba a abajo en el orden de ejecución de WordPress.

Si quieres encontrar filtros para enganchar en el código fuente de WordPress, realiza una búsqueda del término «apply_filters» y obtendrás toneladas de resultados. La Referencia del Código de WordPress también es un gran lugar para buscar todo lo que está incluido en WordPress, incluyendo acciones y filtros.

¿Cómo el núcleo de WordPress utiliza los filtros?

El propio WordPress Core utiliza muchos de sus filtros incorporados para modificar los datos utilizados por sus diversas funciones.

Considera el filtro the_content por ejemplo. Filtra el contenido de los mensajes después de ser recuperado de la base de datos y antes de que se muestre en el navegador.

Al igual que con las acciones, puedes encontrar la mayoría de las funciones de filtro de WordPress Core relacionadas con el gancho the_content en el archivo wp-includes/default-filters.php.

Aquí hay una lista de todas las funciones básicas add_filter() que se enganchan en el filtro the_content:

add_filter( 'the_content', 'do_blocks', 9 );
add_filter( 'the_content', 'wptexturize' );
add_filter( 'the_content', 'convert_smilies', 20 );
add_filter( 'the_content', 'wpautop' );
add_filter( 'the_content', 'shortcode_unautop' );
add_filter( 'the_content', 'prepend_attachment' );
add_filter( 'the_content', 'wp_make_content_images_responsive' );
add_filter( 'the_content', 'do_shortcode', 11 ); // AFTER wpautop(). 

Observa la prioridad especificada para ciertas funciones de devolución de llamada.

Por ejemplo, la función do_blocks() analiza cualquier bloque dinámico en el contenido del post y lo vuelve a hacer compatible con el nuevo editor de bloques de WordPress. Se especifica una prioridad más alta que la predeterminada (10) para asegurarse de que el contenido esté listo para ser bloqueado antes de que se ejecuten las otras funciones.

La función convert_smilies() está configurada para ejecutarse con una prioridad menor ya que su tarea es convertir los smileys de texto en sprites de imagen. Hacer que se ejecute al final después de filtrar todo el contenido del post tiene sentido.

Dato curioso: Los códigos cortos son un subconjunto de filtros. Toman la entrada del código corto, la procesan y luego devuelven la salida a él. Aprende más sobre los códigos cortos en esta guía definitiva de WordPress sobre códigos cortos.

Otras funciones del filtro

Aunque add_filter() es la función de filtro más utilizada, hay muchas otras funciones de filtro útiles. Analicémoslas todas en profundidad.

Esta función comprueba si el filtro especificado está enganchado por alguna función. Acepta dos parámetros. El primer parámetro es para introducir el nombre del filtro. El segundo parámetro es opcional y sirve para introducir el nombre de la función de callback.

has_filter( 'filter_name', 'function_to_check' );

Si especificas sólo el primer parámetro, devolverá true si filter_name está enganchado por cualquier función.

Sin embargo, si se especifican los dos parámetros, entonces devolverá false si la función de callback mencionada no está registrada con el filtro dado. Si encuentra la función de callback registrada con el filtro, entonces devolverá  priority (un entero) establecida para esa función en este filtro.

Una posible aplicación de la función has_filter() es comprobar si algún filtro ya ha sido enganchado, y en base a eso seguir adelante con la ejecución del código.

// check to see if 'the_content' filter has been hooked
if ( ! has_filter( 'the_content' ) {
    // hook the filter if and only if it hasn't been hooked before
    add_filter( 'the_content', 'modify_the_content' );
}

Esta función de filtro es como la función de acción do_action(). Cualquier función de callback enganchada a este filtro se ejecutará dondequiera que esta función esté en el código de WordPress.

También puedes utilizar esta función para crear un nuevo filtro personalizado especificando el nombre del filtro y el valor del mismo como parámetros.

apply_filters( 'filter_name', 'value_to_filter', [argument1], [argument2] );

No olvides especificar cualquier argumento adicional si quieres pasarlo a tus funciones de callback. La mayoría de los filtros sólo usan un argumento, así que es fácil perderse la definición de los adicionales.

Esta función es como la función apply_filters(), excepto que todos los argumentos que acepta están agrupados en un array.

// an example array
$arguments_array = array( 'some_value', 'foo', false, 'another_value' );

apply_filters_ref_array( 'example_filter', $arguments_array );

Esta función de filtrado puede ser útil cuando se tienen muchos argumentos que pasar o si todos ellos ya están en un arreglo. Asegúrate de que los argumentos dentro del array estén en el orden correcto.

Esta función de filtrado recupera el nombre del filtro o la acción actual que se está ejecutando. No es necesario especificar ningún parámetro ya que se ejecuta dentro de la función de callback.

Aquí hay un ejemplo de su uso:

function example_callback() {
    echo current_filter(); // 'the_title' will be echoed
    return
}
add_filter( 'the_title', 'example_callback' );

A pesar de su nombre, esta función puede recuperar el nombre tanto de las acciones como de los filtros.

Esta función de filtro elimina la función de callback asociada al filtro especificado. Funciona exactamente como la función remove_action(). Puedes usarla para eliminar las funciones predeterminadas de WordPress registradas con un filtro específico y, si es necesario, sustituirlas por tus propias funciones.

remove_filter( 'filter_name', 'function_to_be_removed', [priority] );

Para desenganchar una función de callback enganchada a un filtro, los parámetros function_to_be_removed y priority deben ser idénticos a los argumentos utilizados al enganchar la función de callback.

Si el filtro se ha añadido desde dentro de una clase, lo que suele ser el caso cuando se añaden los plugins, entonces hay que acceder a la variable de la clase para eliminar el filtro.

// access the class variable first, and then remove the filter through it
global $some_class;

remove_filter( 'the_content', array($some_class, 'class_filter_callback') );

Veamos un gran ejemplo de remove_filter() en acción.

El plugin WooCommerce utiliza la función de llamada wc_lostpassword_url() enganchada a su filtro lostpassword_url para redirigir «Lost Your Password?» por parte de los usuarios.

Se necesita que cualquier usuario haga clic en ese enlace para una página de inicio personalizada con la URL /mi-cuenta /contraseña-perdida. Sin este filtro, los llevaría a la URL de inicio de sesión estándar de WordPress en /wp-login.php.

Digamos que quiere restablecer esta funcionalidad y enviar a tus usuarios a la página de recuperación de contraseñas predeterminada o a una página completamente separada. Puedes eliminar esta función de callback de la siguiente manera:

remove_filter( 'lostpassword_url', 'wc_lostpassword_url', 10 );

Esta función de filtro elimina todas las funciones de callback registradas en un filtro.

remove_all_filters( 'filter_name', [priority] );

Es similar a la funciónremove_all_actions().

El popular plugin Advanced Excerpts utiliza esta función para eliminar todas las funciones predeterminadas enganchadas a los filtros the_excerpt y get_the_excerpt. Después de hacer eso, entonces engancha su propia función de callback al filtro.

// Ensure our filter is hooked, regardless of the page type 
if ( ! has_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) ) ) {
    remove_all_filters( 'get_the_excerpt' ); 
    remove_all_filters( 'the_excerpt' ); 
    add_filter( 'get_the_excerpt', array( $advanced_excerpt, 'filter_excerpt' ) );
}

Esta función de filtro comprueba si el filtro especificado se está ejecutando en este momento.

if ( doing_filter( 'save_post' ) ) {
    // run your code here
}

Devuelve un valor booleano (true o false).

Debes notar la diferencia entre esta función y la función current_filter(), que devuelve el nombre del filtro o la acción que se está ejecutando (una cadena).

Filtros Ejemplo 1: Añadir un filtro de profanidad para los comentarios

Gestionar todos los comentarios de tu sitio de WordPress puede ser un proceso engorroso. El filtro comment_text te permite establecer reglas para modificar los comentarios antes de que se impriman en la pantalla.

Los comentarios sin filtrar con blasfemias ficticias marcadas

Los comentarios sin filtrar con blasfemias ficticias marcadas

Puedes ordenar a WordPress que elimine automáticamente cualquier comentario antes de que se muestre a los visitantes de tu sitio. Vamos a ello.

// hook into the 'comment_text' filter with the callback function
add_filter( 'comment_text', 'the_profanity_filter' );

// define a callback function to filter profanities in comments 
function the_profanity_filter( $comment_text ) {
    // define an array of profane words and count how many are there 
    $profaneWords = array('fudge', 'darn', 'pickles', 'blows', 'dangit');
    $profaneWordsCount = sizeof($profaneWords);
    
    // loop through the profanities in $comment_text and replace them with '*'
    for($i=0; $i < $profaneWordsCount; $i++) {
        $comment_text = str_ireplace( $profaneWords[$i], str_repeat('*', strlen( $profaneWords[$i]) ), $comment_text );
    } 
    
    return $comment_text;
}

Aquí hay un desglose línea por línea del código:

Guarda los cambios en tu archivo de plugin personalizado y recarga cualquier publicación con comentarios. Todas las palabras que has incluido en la matriz de profaneWords deben ser reemplazadas por símbolos ‘*’.

Censurar la blasfemia en los comentarios con símbolos '*'.

Censurar la blasfemia en los comentarios con símbolos ‘*’.

Los comentarios originales seguirán estando disponibles tal como están en la base de datos. Este filtro sólo modifica el texto de los comentarios antes de que se emita al frontend.

El comentario original en el backend del sitio

El comentario original en el backend del sitio

Una vez que te enganchas al filtro correcto, puedes hacer un montón de cosas geniales con él.

Por ejemplo, también puedes usar el filtro comment_text para eliminar cualquier URL de todos los comentarios (asegúrate de leer esta guía detallada sobre ¿Cómo detener los comentarios de spam en WordPress?).

O puedes engancharte al filtro pre_comentario_aprobado y marcar los comentarios como aprobados, spam, o thrash basado en criterios predefinidos.

Filtros Ejemplo 2: Insertar contenido después de un post

Ya has visto cómo WordPress utiliza el filtro the_content para modificar el contenido de los mensajes o de la página. Usemos el mismo filtro para añadir algo al final de cada post.

// hook into 'the_content' filter with a callback function
add_filter( 'the_content', 'insert_content_below' );

// define the callback function to insert something below the post
function insert_content_below( $content ) {
    // check to see if we're inside the main loop in a single post
    if ( is_single() && in_the_loop() && is_main_query() ) {
        return $content . "<h3 style=\"text-align: center;\">Let me insert myself here</h3><p style=\"text-align: center;border: 3px solid #5333ed;\">I'll appear after the post. You can insert anything here. Even HTML. Headers, links, images, scripts, I'll take them all and append it to the end of the post content. You can also give me a class, so you can style me easily with CSS style sheets.</p>" ;
    } 
    
    return $content;
}

Entendiendo la lógica del código en el ejemplo anterior:

Guarda tu archivo de plugin, carga cualquier publicación en tu sitio y desplázate hasta el final.

Insertar algo al final del contenido del post

Insertar algo al final del contenido del post

Puedes usar la misma lógica para añadir cualquier cosa al principio de todos tus posts invirtiendo la posición de los parámetros de concatenación de cadenas ("tus adiciones" . $contenido).

¿Necesita un alojamiento rápido, seguro y fácil de desarrollar para los sitios de sus clientes? Kinsta está construido con los desarrolladores de WordPress en mente y proporciona un montón de herramientas y un potente panel de control. Vea nuestros planes.

Personalizar la página de inicio de sesión de WordPress con ganchos

Usemos tanto acciones como filtros para personalizar la página de inicio de sesión predeterminada de WordPress. Para ello, crearé un nuevo plugin llamado Página de inicio de sesión personalizada de Sal. Puedes encontrar el código fuente completo de este plugin al final de esta sección.

La última pantalla de acceso personalizada de WordPress

La última pantalla de acceso personalizada de WordPress

Comencemos agregando los campos de encabezado del plugin estándar y registrándolo en WordPress.

<?php

/*
Plugin Name:  Sal Custom Login Page
Version:  1.0
Description:  Demonstrating WordPress Hooks (Actions and Filters) by customizing the WordPress login page.
Author:  Salman Ravoof
Author URI:  https://www.salmanravoof.com/License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html
Text Domain:  sal-custom-login-page
*/

// enqueueing the custom style sheet on WordPress login page
add_action( 'login_enqueue_scripts', 'salhooks_login_stylesheet');
function salhooks_login_stylesheet() {
    // Load the style sheet from the plugin folder
    wp_enqueue_style( 'sal-custom-login-page', plugin_dir_url( __FILE__ ).'sal-custom-login-page-styles.css' );
}

Primero, engancha la acción login_enque_scripts para poner en cola tu hoja de estilo personalizada. Todos los scripts o estilos que pongas en cola aquí se incluyen en la sección de encabezado de tu página de inicio de sesión.
Si quieres cargar scripts personalizados y hojas de estilo en el frontend de tu sitio (en lugar de en el backend de administración o en el área de login), entonces necesitas engancharte a la acciónwp_enqueue_scripts. Puedes leer más sobre ello en el Codex de WordPress y en el artículo de Kinsta sobre ¿cómo usar wp_enqueue_scripts?

Dentro de la función callback salhooks_login_stylesheet(), usa la función wp_enqueue_style() para cargar la hoja de estilo personalizada (sal-custom-login-page-styles.css) colocada en el mismo directorio del plugin. La función ( __FILE__ ) incorporada en WordPress facilita la obtención de la ruta URL (con una barra inclinada) del directorio actual del plugin.

No voy a explicar los estilos CSS aplicados aquí, pero puedes encontrarlos todos en el código fuente enlazado al final de esta sección.

// Custom login ERROR message to keep the site more secure
add_filter( 'login_errors', 'salhooks_remove_login_errors', 10 );
function salhooks_remove_login_errors() {
    return 'Incorrect credentials. Please try again!';
}

A continuación, enganché el filtro login_errors para cambiar el mensaje de error que se muestra cuando alguien introduce credenciales incorrectas. Filtrar el mensaje de error evitará que los atacantes adivinen tu nombre de usuario fácilmente.

// Remove the login form box shake animation for incorrect credentials
add_action( 'login_head', 'remove_login_error_shake' );
function remove_login_error_shake() {
    remove_action( 'login_head', 'wp_shake_js', 12 );
}

Cada vez que alguien introduce credenciales de acceso incorrectas, el cuadro del formulario de acceso se agita agresivamente. Este es un paso opcional, pero lo he incluido para mostrar que también se pueden eliminar ciertas características de la página de inicio de sesión.

Aprenderás más sobre las funciones remove_action() y remove_filter() en la sección final de este artículo.

// Change the logo and header link above the login form
add_filter( 'login_headerurl', 'salhooks_login_headerurl');
function salhooks_login_headerurl( $url ) {
    $url = 'https://salmanravoof.com';
    return $url;
}

add_filter( 'login_headertext', 'salhooks_login_headertext');
function salhooks_login_headertext( $text ) {
    $text = 'Salman Ravoof';
    return $text;
}

El último paso es cambiar la URL y el texto del encabezado de la sesión. Puedes enganchar los filtros login_headerurl y login_headertext para modificar ambos.

Si quieres construir sobre este plugin y experimentar más, puedes descargar el código fuente del plugin y comenzar.

Lista de ganchos y recursos de WordPress

Es difícil memorizar todos los diversos ganchos que tiene WordPress. Hay miles de acciones y filtros incorporados para enganchar. Por lo tanto, encontrar un gancho apropiado puede parecer a veces una búsqueda del tesoro.

Afortunadamente, hay varios recursos que puedes usar para identificar el gancho perfecto para tus necesidades.

El primer lugar para familiarizarse con los ganchos es el Codex de WordPress, en particular su sección de ganchos en el manual de plugins. Aquí puedes encontrar información esencial sobre los ganchos y enlaces a la documentación completa sobre todas las acciones y filtros.

Empieza a aprender ganchos con el manual de plugins de WordPress

Empieza a aprender ganchos con el manual de plugins de WordPress

Marca estos útiles enlaces del Manual de complementos para acelerar tu búsqueda:

Tanto la página de referencia de la acción como la de referencia del filtro te darán una lista de todos los ganchos que suelen funcionar durante una solicitud específica de WordPress.

Por ejemplo, puedes encontrar todos los ganchos disparados cuando accedes a una página de administración, cuando te ocupas de los archivos adjuntos de una página de correo o de las categorías.

El Codex de WordPress también incluye una práctica herramienta de búsqueda para encontrar todas sus funciones, ganchos, métodos y clases. Esta página también enumera los componentes nuevos y actualizados en la versión más reciente de WordPress. Dirígete aquí primero si quieres encontrar lo que está pasando dentro de WordPress.

Busca cualquier cosa dentro de WordPress aquí

Busca cualquier cosa dentro de WordPress aquí

Este índice de ganchos de WordPress clasifica todos los ganchos por tipo, la versión de WordPress en la que debutaron, y si son obsoletos.

El índice de ganchos de WordPress de Adam R Brown

El índice de ganchos de WordPress de Adam R Brown

Clasificando los ganchos en orden de su apariencia te mostrará que los ganchos más antiguos de WordPress siguen siendo los más usados. Si eres nuevo en el desarrollo de WordPress, familiarizarte con estas acciones y filtros populares es la manera más rápida de ponerte al día.

Aunque este índice no ha sido actualizado desde WordPress 5.1, sigue siendo útil para hojear todos los ganchos principales.

¿Todavía te cuesta encontrar el gancho que quieres? Una búsqueda en línea con la palabra clave correcta es siempre una buena manera de empezar. Si todo lo demás falla, siempre puedes buscar en el código de WordPress.

Encontrar ganchos registrados en una página de WordPress

Como hemos visto, WordPress tiene toneladas de ganchos disponibles, pero no todos los ganchos se disparan en cada página. Si puedes encontrar qué acciones y filtros puedes enganchar en una página en particular, entonces has ganado la mitad de la batalla.

Aunque puedes usar herramientas avanzadas de depuración de PHP como xdebug y PHPCS para ayudar con esto, hay herramientas de desarrollo más sencillas como Debug Bar y Query Monitor que puedes ejecutar dentro de WordPress.

Debug Bar con acciones y filtros adicionales

Debug Bar es un plugin oficial de WordPress que agrega un menú Debug a tu barra de administración. Muestra advertencias y avisos de PHP, solicitudes de caché, consultas de MySQL y otra información útil de depuración.

Info

Este plugin no ha sido actualizado recientemente, ni probado con las últimas versiones importantes de WordPress. Lo mencionamos como un plugin útil para aprender más sobre los ganchos de WordPress. Utilízalo en un entorno de staging.

WordPress Debug Bar WordPress plugin

WordPress Debug Bar WordPress plugin

Después de instalar el plugin, debes agregar el siguiente fragmento de código al archivo wp-config.phpde tu sitio para habilitar sus funciones de depuración.

define( 'WP_DEBUG', true ); // tracks PHP Warnings and Notices
define( 'SAVEQUERIES', true ); // tracks and displays MySQL queries

Ahora deberías ver que la opción del menú de depuración aparece en tu barra de administración. Al hacer clic en ella te llevará a su panel de control donde podrás ver varias consultas y cachés adjuntos a la página desde la que has accedido.

El menú

El menú «Debug» en la barra de administración de WordPress

A continuación, debes instalar el plugin Debug Bar Actions and Filters Addon. Es una extensión muy útil que añadirá dos pestañas más al panel de la Barra de depuración para mostrar las acciones y los filtros activados en la solicitud actual.

Las acciones enumeradas en su orden de carga para la página actual

Las acciones enumeradas en su orden de carga para la página actual

También enumerará todas las funciones enganchadas a ellos con su prioridad.

El plugin de Degug Bar con el Addon de Acciones y Filtros instalado

El plugin de Degug Bar con el Addon de Acciones y Filtros instalado

Puedes hacer clic en el menú Debug desde cualquier página de tu sitio para conocer todas las acciones y filtros que puedes enganchar en esa página.

Query Monitor

Query Monitor es un poderoso panel de herramientas de desarrollo para WordPress. Puedes usarlo para indagar en los ganchos disponibles en una página y su orden de carga.

Query Monitor WordPress plugin

Query Monitor WordPress plugin

A diferencia de Debug Bar no tienes que instalar ningún complemento para ver las acciones y los filtros que se activan en una página determinada.

Puedes acceder al Query Monitor desde la barra de administración

Puedes acceder al Query Monitor desde la barra de administración

El Query Monitor también te da más información acerca de dónde exactamente se dispara un gancho.

El panel Hooks & Actions en Query Monitor

El panel Hooks & Actions en Query Monitor

En la columna de componentes, se puede ver que la mayoría de los ganchos están registrados desde el núcleo. Pero algunos ganchos se registran desde un tema o un plugin. Algunos ganchos pueden estar registrados desde más de un componente.

Puedes usar los desplegables de ganchos y componentes para ver sólo los ganchos que necesitas.

Nota: Query Monitor utiliza «Ganchos» como término general tanto para las acciones como para los filtros, pero llama a las funciones de callback registradas como «Acciones». Esta es técnicamente una definición errónea y puede confundirte, así que tenlo en cuenta.

Puedes hacer más que comprobar todas las consultas y peticiones con Query Monitor. También incluye características avanzadas como estilos de listado, scripts, lenguajes, llamadas Ajax, comprobaciones de capacidad de usuario y llamadas a la API de REST.

«all» Hook

WordPress tiene un gancho especial llamado «all» que puedes enganchar para ejecutar una función de callback para cada uno de los ganchos, independientemente de si está registrado en todos ellos. Es útil para depurar fallos de página o si quieres saber cuando un evento en particular está sucediendo.

Por ejemplo, puedes usar el gancho all como en el ejemplo de abajo para hacer eco de todas las acciones que se están ejecutando.

// echo all the actions being run
function debug_helper_function(){
    echo '<p>' . current_action() . '</p>';
}
add_action( 'all', 'debug_helper_function' );

La debug_helper_function() definida anteriormente se ejecutará cuando se dispare cualquier acción. Saber cuál fue la última acción ejecutada te dará una mejor idea de dónde tienes que buscar.

¿Dónde se guardan los ganchos de WordPress?

WordPress usa la clase WP_Hook para implementar cómo funcionan los ganchos. Esta clase central se usa para manejar todas las acciones y filtros de WordPress incorporados. Puedes encontrar casi todo el código relacionado con esta clase en el archivo wp-includes/class-wp-hook.php.

Técnicamente, la clase WP_Hook es un arreglo de objetos que comprende propiedades como callbacks, iteraciones, current_priority, nesting_level, y doing_action. También define un montón de útiles funciones gancho que pueden ser llamadas usando los métodos WP_Hook.

La mayoría de los desarrolladores de WordPress no tienen que preocuparse mucho por dónde almacena WordPress los ganchos siempre que se atengan a las directrices de la API de los plugins.

Hay dos tipos de ganchos de WordPress: acciones y filtros, y esta guía desglosa exactamente cuándo (¡y cómo!) usar cada uno 💥Click to Tweet

¿Cómo crear tus ganchos personalizados de WordPress?

Has visto los diversos ganchos que WordPress proporciona a través de su Plugin API. También has visto cómo puedes usar los ganchos predeterminados para inyectar tu propio código en el tiempo de ejecución de WordPress.

Si eres un desarrollador de plugins o de temas, es una buena práctica proporcionar a otros desarrolladores una forma de interactuar con tu código de la misma manera. Los ganchos personalizados te permiten hacer exactamente eso. Permiten a otros desarrolladores ampliar y modificar la funcionalidad de tus plugins y temas.

Crear tus propias acciones y filtros es bastante simple. Utilizas las mismas funciones que usa WordPress Core para crear ganchos. Veamos algunos ejemplos.

¿Cómo crear acciones personalizadas en WordPress?

Utiliza la funcióndo_action() para crear un gancho de acción personalizado. Así es como se hace:

// the position where you insert your action is where it'll run when called
do_action( ' my_unique_custom_action' );
// continue with the rest of your code

Ahora, otros desarrolladores pueden engancharse a tu plugin o tema sin modificar el código fuente. Todo lo que tienen que hacer es registrar sus funciones de callback a la acción personalizada de tu plugin usando la función add_action().

add_action( 'my_unique_custom_action', 'some_callback_function' );

// define the callback function you mentioned in the above action function
some_callback_function() {
     // this code will run wherever your custom action hook is 
}

Asegúrate de documentar bien tus ganchos personalizados, explicando en detalle lo que hacen. Después de todo, el uso principal de la creación de ganchos personalizados es ayudar a otros desarrolladores a interactuar con tu código.

¿Cómo crear un filtro personalizado en WordPress?

Utiliza la funciónapply_filters() para crear un gancho de filtro personalizado. Así es como puedes hacerlo:

$value_to_filter = "I'm a string, but this can be any PHP data type";

// filters modify a value and are typically tied to a predefined variable
apply_filters( 'my_custom_filter', $value_to_filter );

Los parámetros de tu filtro personalizado deben incluir un identificador único y un valor a filtrar. Otros desarrolladores pueden engancharse a tu filtro personalizado con la función add_filter() y modificar el valor pasado.

add_filter( 'my_custom_filter', 'some_callback_function' );

// define the callback function you mentioned in the above filter function
function some_callback_function( $value_to_filter ) {
    // modify the passed value (or not) 
    return $value_to_filter; // returning a value is a must for filters
}

Cuando definas tu filtro personalizado, asegúrate de que no se posicione antes de que se defina el valor que se supone que debe filtrar. Si no posiciona el filtro correctamente, el valor filtrado será sobrescrito por el valor predeterminado después.

Convención sobre la denominación de los ganchos personalizados

Es importante elegir un nombre único para todos sus ganchos personalizados. Dado que cualquier plugin o tema puede tener sus propios ganchos personalizados, tener nombres de ganchos idénticos puede causar colisiones de códigos con resultados inesperados.

Por ejemplo, si llamas a tu acción send_email, es muy probable que otros desarrolladores de plugins también escojan el mismo término ya que no es lo suficientemente único. Si un sitio web instala tanto los plugins suyos como los de otros desarrolladores, puede causar errores que serán difíciles de rastrear.

Puedes ponerle un prefijo a todos tus anzuelos personalizados con un identificador común para que sean simples y únicos. Así, en lugar de send_email, puedes nombrarlo plugin_name_send_email (plugin_name_ es el prefijo único aquí).

Demostración de Custom Hooks con un plugin extensible

Vamos a crear un plugin extensible (o un plugin enchufable) que permita a otros desarrolladores interactuar con él usando sus ganchos personalizados.

Nombraré a este plugin «Custom Hooks Demo». Su función principal es producir un cuadro de citas dondequiera que se inserte un atajo. Incluirá acciones y filtros personalizados en los lugares adecuados para que otros desarrolladores puedan modificar o ampliar su funcionalidad.

Puedes consultar mi guía de atajos de WordPress para saber más sobre cómo funcionan los atajos.

Empecemos con el plugin extensible.

<?php

/*
Plugin Name :  Custom Hooks Demo
Description :  Demonstrating how to create an extensible WordPress plugin using custom hooks.
Author      :  Salman Ravoof
Author URI  :  https://salmanravoof.com/
License     :  GPLv2 or later
License URI :  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain :  custom-hooks-demo
*/

/** 
 * the [custom_hooks_demo] shortcode returns the HTML code for a quote box.
 * @return string HTML code for a quote box
*/
add_shortcode( 'custom_hooks_demo', 'my_shortcode_callback' );

function my_shortcode_callback ( $arguments ) {
    ob_start(); // start object buffering to collect all output before sending it to the browser
    
    // set an action hook to run before you output anything
    do_action( 'the_topmost_custom_action' );
    
    // define your variables which you want to allow to be filtered
    $quote_content = "Z.E.R.O. That's the number of people who'd like to have any website autoplay music on their browsers.";
    $quote_author = "John Doenuts";
    
    // create your custom filters after you've set the variables
    $quote_content = apply_filters( 'custom_quote_content', $quote_content );
    $quote_author = apply_filters( 'custom_quote_author', $quote_author );
    
    // build the shortcode output template
    echo "<div style=\"border:3px solid #5333ed;\"><blockquote style=\"margin:20px;border-color:#5333ed;\">";
    echo $quote_content;
    echo "<br><br>";
    echo "― <strong>" . $quote_author . "</strong>";
    echo "</blockquote></div>";
    
    // set an action hook to run after you output everything
    do_action( 'the_ending_custom_action' );
    
    return ob_get_clean(); // get buffer contents, delete the buffer, and then stop buffering
}

Una vez guardado y activado, al añadir el atajo [custom_hooks_demo] al contenido de la publicación, aparecerá un cuadro de citas con los valores predeterminados.

El cuadro de cotización original usando el plugin Custom Hooks Demo

El cuadro de cotización original usando el plugin Custom Hooks Demo

Ahora, vamos a crear otro plugin llamado Custom Hooks Demo Extension. Se enganchará a todos los ganchos personalizados creados por el plugin anterior y hará o modificará algo.

<?php

/*
Plugin Name :  Custom Hooks Demo Extension
Description :  Demonstrating how you can extend WordPress plugin functionality with its custom hooks.
Author      :  Salman Ravoof
Author URI  :  https://salmanravoof.com/
License     :  GPLv2 or later
License URI :  https://www.gnu.org/licenses/gpl-2.0.html
Text Domain :  custom-hooks-demo-extension
*/

/**
 * replace the quote content by hooking into the 'custom_quote_content' filter
*/
add_filter( 'custom_quote_content', 'new_quote_content_callback' );
function new_quote_content_callback( $content ) {
    $content = "There are no bugs in programming. Only unexpected features.";
    return $content;
}

/**
 * replace the quote author by hooking into the 'custom_quote_author'
*/
add_filter( 'custom_quote_author', 'new_quote_author_callback' );
function new_quote_author_callback( $author ) {
    $author = "Jane Doodle";
    return $author;
}

/**
 * add an image to the top of the shortcode output by hooking into the 'the_topmost_custom_action'
*/
add_action( 'the_topmost_custom_action', 'quote_image_callback' );
function quote_image_callback() {
    $url = "https://upload.wikimedia.org/wikipedia/commons/thumb/f/f9/Quote-right-cs.svg/75px-Quote-right-cs.svg.png";
    echo '<div><img class="aligncenter" src="'.$url.'"></div>';
}

/**
 * add a button below the shortcut output by hooking into the 'the_ending_custom_action'
*/
add_action( 'the_ending_custom_action', 'add_button_callback' );
function add_button_callback() {
    echo '<div style="text-align:center;"><button name="nice">Nice Quote!</button></div>';
}

Como puedes ver, este plugin de extensión no contiene nada más que funciones de acción y filtro que se enganchan en el plugin original en los lugares adecuados para hacer modificaciones.

Utiliza las funciones add_action() y add_filter() para registrar sus funciones de callback con las acciones y filtros personalizados creados por el plugin original (por ejemplo, the_topmost_action, custom_quote_author).

The modified quotation box after the extension plugin changes the original output

The extension plugin modifies the original quotation box

Los ganchos de acción personalizados te permiten interponer tu código en los intervalos correctos en el plugin original y ejecutar tus propios guiones. Aquí, estamos añadiendo una imagen en la parte superior y un botón en la parte inferior.

Asimismo, los ganchos de filtro personalizados permiten modificar los valores del contenido de la cita y su nombre de autor. El resultado final es un plugin que es completamente extensible por cualquiera sin modificar su código fuente.

Trabajando con ganchos personalizados de desarrolladores de terceros

Los ganchos personalizados permiten que los plugins y temas individuales de WordPress tengan un rico ecosistema de plugins extensibles. Considere el plugin WooCommerce. Añade funcionalidad de comercio electrónico a WordPress, pero también incluye toneladas de ganchos dentro de su código.

Acción de WooCommerce y referencia del gancho de filtro

Acción de WooCommerce y referencia del gancho de filtro

WooCommerce tiene cientos de extensiones y plugins que usan sus ganchos para construir su funcionalidad principal y hacerla aún mejor.

Puedes usar estas extensiones para integrar WooCommerce con Stripe, MailChimp, Salesforce, Zapier, y mucho más.

Las extensiones amplían la funcionalidad de WooCommerce

Las extensiones amplían la funcionalidad de WooCommerce

Una buena práctica es revisar la sección de documentación de los populares plugins de WordPress para ver cómo implementan los ganchos personalizados. Algunas de mis principales sugerencias son Easy Digital Downloads, BuddyPress, Quiz y Survey Master, y Gravity Forms.

¿Cuándo usar los ganchos personalizados?

Dependiendo del tema o plugin que estés creando, y para quién esté destinado, puede que te preguntes si necesitas añadir algún gancho personalizado.

Una buena regla empírica a la hora de decidir si se añaden o no ganchos personalizados es comprobar si ofrecen algún beneficio de extensibilidad a otros desarrolladores. Si no es así, es mejor esperar hasta que otros desarrolladores le pidan que los añada.

Tienes que estar muy seguro de añadir ganchos personalizados a tu plugin o tema. Una vez que se publica, y si otros desarrolladores ya lo han usado, no puedes cambiarlo sin romper la compatibilidad retroactiva.

Eliminar las funciones de callback de los ganchos de WordPress

Ya has visto ejemplos de cómo eliminar las funciones de callback registradas en ciertos ganchos. Estas callbacks pueden ser registradas por plugins, temas, o incluso el propio WordPress Core. Veamos la eliminación de las funciones de devolución de llamada de ganchos con más ejemplos.

Para eliminar una función de callback de un gancho, dependiendo de si está registrada en una acción o en un filtro, es necesario utilizar las funciones remove_action() o remove_filter().

Una advertencia es que hay que llamar a estas funciones con los mismos parámetros utilizados para registrar la función de callback. Básicamente, copiar-pegar los parámetros de sus funciones add_action() o add_filter().

Además, puedes eliminar las funciones de callback sólo después de que se registren. Si intentas eliminarlas antes de que se registren, el proceso de eliminación fallará. Necesitas conseguir la orden de ejecución de los ganchos correctamente.

Digamos que quieres eliminar una función de callback registrada por un tema que añade hinchazón a tu sitio (quieres un sitio rápdo ¿verdad?).

function wp_bloated_callback_function() {    
// some code that adds a lot of bloat to the site
}
add_action( 'template_redirect', 'wp_bloated_callback_function', 5 );

Por ejemplo, la función de callback anterior podría cargar muchos guiones y hojas de estilo innecesarios. Eliminarla te dará a tu sitio un enorme impulso de rendimiento.

Sin embargo, es necesario asegurarse de que la función remove_action() se ejecuta sólo después de la acción template_redirect. Una forma de hacer esto es engancharse a la acción after_setup_theme como se activa después de la acción template_redirect.

function wp_remove_bloat() {
    // ensure all parameters are identical to the original add_action() function
    remove_action( 'template_redirect', 'wp_bloated_callback_function', 5 );
}

// ensure that remove_action() is called only after add_action()
add_action( 'after_setup_theme', 'wp_remove_bloat' );

La wp_bloated_callback_function() se desenganchará ahora de la acción template_redirect.

Casos especiales para eliminar las funciones de callback

Hay más en la eliminación de las funciones de callback que en su desactivación total. A veces puede que necesites eliminarlas temporalmente, ejecutar tu código y luego volver a añadirlas.

Por ejemplo, la acción save_post se dispara cada vez que se llaman las funciones wp_insert_post() y wp_publish_post(). Puedes encontrarlas ambas definidas en el archivo wp-includes/post.php.

Por lo tanto, si tienes una función de callback enganchada a la acción save_post, y si llamas a las funciones wp_insert_post() o wp_publish_post() dentro de tu función de callback, la acción save_post se disparará varias veces.

function some_callback_function( $post_id, $post ) {
    // do something here
    wp_insert_post( [some_array] ); // this function also calls the 'save_post' action
    // maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );

Una función que llama a la acción que también la llama puede crear resultados inesperados. Una forma de evitar este problema es usar la función remove_action() dentro de la función de llamada antes de llamar a wp_insert_post().

function some_callback_function( $post_id, $post ) {
    // do something here
    
    // remove the callback function from the ‘save_post’ action
    remove_action( 'save_post', 'some_callback_function', 10, 2 );
    
    // now run the wp_insert_post() function
    wp_insert_post( [some_array] );
    
    // add the callback function back to the ‘save_post’ action
    add_action( 'save_post', 'some_callback_function', 10, 2 );
    
    // maybe do something more
}
add_action( 'save_post', 'some_callback_function', 10, 2 );

Ese es otro uso práctico de las funciones remove_action() o remove_filter(). Profundizar en el núcleo de WordPress te ayudará a entender cómo puedes evitar mejor estas situaciones.

Tutoriales adicionales de WordPress Hooks

Los ganchos de WordPress son una de las herramientas más importantes para tener en el arsenal de un desarrollador de WordPress. 💪 Aprende la diferencia entre acciones y filtros (y cómo usarlos) en esta guía!Click to Tweet

Resumen

Hay múltiples ventajas de usar ganchos de WordPress si eres un desarrollador de WordPress.

Los ganchos no sólo te permiten modificar o ampliar la funcionalidad básica de WordPress, sino que también puedes usarlos para modificar plugins, temas y permitir que otros desarrolladores interactúen con tus plugins o temas.

¡Es hora de engancharse a los ganchos de WordPress!


Si le ha gustado este artículo, entonces le encantará la plataforma de Kinsta WordPress hosting. Acelere su sitio y reciba soporte 24/7 de nuestro equipo de WordPress veterano. Nuestra infraestructura potenciada por Google Cloud se centra en escalamiento automático, rendimiento y seguridad. ¡Déjenos mostrarle la diferencia con Kinsta! Conozca nuestros planes