Guía: Todo sobre Hooks en WordPress
¿Alguna vez le han dicho que la solución a su problema es que necesita "engancharse" a algo para hacer lo suyo o lo usa add_filtersin entender realmente por qué estropea las cosas? Los ganchos constituyen la base de WordPress y proporcionan temas y complementos una forma de interactuar o modificar código En esta publicación, desglosaremos qué son los ganchos, cómo funcionan y cómo podemos usarlos.
¿Qué son los ganchos?
A medida que WordPress ejecuta su código (desde el comienzo de la carga de clases, la carga de complementos, la carga del tema, la consulta de la solicitud actual y finalmente la representación del HTML), pasa por un montón de "puntos de control"; manos. Cuando se encuentra un gancho, WordPress detendrá lo que está haciendo y verificará si hay alguna función (en el tema, el complemento o el propio WordPress) que esté registrada para ejecutarse en este gancho. Si las hay, WordPress ejecutará todas esas funciones y luego continuará donde lo dejó.
Esto hace posible que los complementos, los temas y el propio WordPress se "enganchen" a ciertos puntos para agregar, por ejemplo, hojas de estilo en la <head>etiqueta del tema, modificar cómo WordPress consulta las publicaciones o simplemente cambiar el contenido de la publicación si así lo desea.
Hay dos tipos de anzuelos; acciones y filtros. Funcionan de manera bastante similar entre sí, pero con una excepción que veremos más de cerca a continuación.
Acciones y filtros
Para conectarse a una acción o filtro, debe definir qué enlace (por su nombre) desea usar y definir una devolución de llamada, que es el nombre de la función que desea ejecutar. En la mayoría de los casos, los ganchos proporcionan parámetros o variables que son relevantes para el gancho.
Las acciones son simplemente “puntos de control" en la ejecución de WordPress, donde puedes realizar una tarea o hacer eco de algo. En algunos casos raros, puede modificar un objeto (proporcionado en los parámetros), de modo que todas las ejecuciones siguientes funcionen con ese objeto modificado.
Los filtros son para cambiar una variable o salida. Todos los enlaces de filtro proporcionarán la variable que puede cambiar como primer parámetro y le permitirán modificarla o devolver algo diferente.
WordPress ejecuta muchos ganchos, pero puede crear los suyos propios en su complemento o tema. Esto permite a los desarrolladores ampliar y modificar su código; por ejemplo, modificar un complemento a través de un tema o modificar el tema principal a través del tema secundario.
Muchas de las funciones de WordPress, que normalmente se usan para imprimir publicaciones, también son filtros o acciones. Por ejemplo, la función the_title()imprime el título de la publicación, pero también es un filtro.
Veamos cómo los conectamos en la práctica.
Enganchado a acciones
Para engancharte a una acción, usas el método add_action(). Como mínimo requiere dos parámetros; el nombre del enlace y la devolución de llamada; el nombre de la función que desea ejecutar. Opcionalmente, puede proporcionar prioridad como tercer parámetro y definir la cantidad de argumentos que se pasarán a su función de devolución de llamada. Veremos los dos parámetros opcionales más adelante, pero por ahora, aquí hay un ejemplo de add_action:
add_action('init', 'my_function_name');
function my_function_name() {
// Do your stuff
}El primer parámetro para add_actiones el nombre de la acción; en este caso init, que es un gancho de WordPress bastante común que ocurre durante la inicialización. El segundo parámetro es su devolución de llamada, en este caso el nombre de la función que deseamos ejecutar. Luego, todo lo que necesita hacer es definir una función con ese nombre y agregar su código dentro de ella.
También puede usar funciones anónimas, que es donde define la función interna add_actionen lugar de proporcionar un nombre de función, así;
add_action('init', function() {
// Do your stuff
});Muchos desarrolladores prefieren este método ya que evita el riesgo de redefinir una función de PHP con el mismo nombre.
Si necesita ejecutar una función definida dentro de una clase de PHP, debe proporcionar una matriz como parámetro de devolución de llamada; donde el primer elemento es el objeto de clase y el segundo elemento es el nombre de la función:
class MyClass {
public function __construct() {
add_action('init', [$this, 'myFunctionName']);
}
public function myFunctionName() {
// Do your stuff
}
}Enganchado a filtros
Para enganchar a un filtro, utiliza la función add_filter(). De manera similar a las acciones anteriores, el primer parámetro es el nombre del filtro y el segundo es su devolución de llamada. Opcionalmente, puede proporcionar la prioridad como tercer parámetro y el número de argumentos como cuarto. Aquí hay un ejemplo de add_filter:
add_filter('the_title', 'my_function_name');
function my_function_name($title) {
// Do your stuff
return $title;
}En el ejemplo anterior, nos conectamos al filtro the_title(que imprime el título de la publicación) y le indicamos a WordPress que ejecute nuestra función. Todos los filtros siempre proporcionarán un argumento; la variable a cambiar. En mi función lo nombré porque $titlesé que contiene el título de la publicación. Dentro de la función puedo modificarla o anular completamente la variable. Es importante recordar que en los filtros siempre debes devolver la variable. Si no devuelve algo en su función de devolución de llamada, la variable se vacía. Si omití la declaración de devolución en el ejemplo anterior, ningún título de publicación haría eco en ninguna parte.
El argumento variable y la regla de devolver algo en su función de devolución de llamada es prácticamente la única diferencia entre filtros y acciones. Todo lo demás funciona igual. Puede seguir los ejemplos de funciones y clases anónimas que se muestran para las acciones anteriores para los filtros, así como la prioridad de los parámetros opcionales y la cantidad de argumentos; que veremos a continuación.
Prioridad
El tercer parámetro (opcional) de add_actiony add_filteres un número entero que define la prioridad de su función de devolución de llamada. Esto es útil en los casos en que hay múltiples funciones (no necesariamente de usted en su tema o complemento, recuerde que WordPress usa sus propios ganchos) y necesita decidir cuál ejecutar primero.
Si no se proporciona ninguna prioridad, el valor predeterminado es 10. Cuanto menor sea la prioridad, antes se ejecutará, y cuanto mayor sea la prioridad, más tarde se ejecutará. No puede proporcionar una prioridad negativa.
Imagine varias funciones de devolución de llamada registradas en init. Si no se proporcionó prioridad para varias devoluciones de llamada, WordPress las ejecutará en el orden en que se encontraron (por ejemplo, en functions.phpel código de su complemento).
add_action('init', 'my_function_name');
add_action('init', 'my_second_function_name');
add_action('init', 'my_third_function_name', 12);
add_action('init', 'my_fourth_function_name', 1);Este sería el orden en el que WordPress ejecutará las devoluciones de llamada anteriores:
my_fourth_function_name(Prioridad 1)my_function_name(prioridad 10)my_second_function_name(prioridad 10, pero aparece más tarde en el código)my_third_function_name(prioridad 12)
Número de argumentos
Por lo general, los enlaces proporcionan algunos datos adicionales que son relevantes y útiles para las funciones de devolución de llamada. Por ejemplo, la acción save_post(se ejecuta cada vez que se actualiza una publicación) proporciona dos argumentos posibles; el ID de la publicación y el objeto de la publicación. Estos son útiles para las operaciones que normalmente necesita ejecutar en este enlace (por ejemplo, si desea guardar una publicación meta, necesita la ID de la publicación).
Si no se proporcionó una cantidad de argumentos para una acción o filtro, el valor predeterminado es 1. Es por eso que no necesita definir 1 add_filterpara acceder a la variable a la que está conectado el filtro. Sin embargo, las acciones no pueden pasar argumentos aunque el número de argumentos esté establecido en 1 de forma predeterminada.
Veamos un ejemplo de cómo definir el número de argumentos y cómo accedemos a ellos en nuestra función de devolución de llamada:
add_action('save_post', 'my_function_name', 10, 2);
function my_function_name($post_id, $post) {
// Do your stuff
}En el ejemplo anterior, le decimos a WordPress que pase dos argumentos a nuestra función de devolución de llamada. Recuerde que necesitamos definir la prioridad como tercer parámetro, por lo que generalmente definimos el valor predeterminado, que es 10. En cuanto a nuestra función de devolución de llamada, ahora podemos definir los mismos argumentos numéricos que solicitamos, en el ejemplo anterior fue 2.
Si en el ejemplo anterior tuviéramos establecido el número de argumentos en 1, solo se completaría el primer argumento en nuestra función de devolución de llamada. El segundo, $postsería indefinido.
¿Qué sucede si necesitamos datos que no se pasaron en el enlace?
Depende totalmente del desarrollador que creó el enlace definir qué argumentos se pueden pasar. Esto significa que no puede simplemente forzar qué argumentos desea o necesita en su add_actiono add_filter. Por suerte en la mayoría de los casos tenemos alternativas para conseguir las variables que necesitamos. Si se conecta a una acción o filtro donde sabe que se deben definir ciertas variables globales, puede acceder a estas variables globales en su función de devolución de llamada. Además, WordPress tiene una amplia gama de etiquetas condicionales que puede usar en sus funciones enganchadas (con la excepción de los enlaces muy tempranos que ocurren antes de que WordPress defina estas etiquetas condicionales)
Veamos un ejemplo de acceso a variables globales. El filtro the_titleproporciona el ID de la publicación como argumento opcional, al que podemos acceder definiéndolo como un argumento aceptable;
add_filter('the_title', 'my_function_name', 10, 2);
function my_function_name($title, $post_id) {
if ($post_id == 1) {
return 'First post ever!';
}
return $title;
}Sin embargo, podemos lograr el mismo resultado por;
Si sabe que una variable global está definida por el punto en que se ejecuta el enlace, puede definirla como global en su función de devolución de llamada y acceder a los datos desde allí. Por ejemplo, definir global $wp_queryen el ejemplo anterior también le daría acceso al objeto wp_query completo dentro de la devolución de llamada de su función.
Las etiquetas condicionales de WordPress son extremadamente útiles. A menos que esté enganchado a un gancho que ocurre muy temprano en la ejecución de WordPress, están disponibles. Hay etiquetas condicionales para verificar en qué página (plantilla) se encuentra, si está dentro de un menú o un ciclo de publicación, y mucho más. Por ejemplo, al modificar la consulta de publicación usando el enlace pre_get_posts, es muy útil asegurarse de que su código solo se ejecute en ciertos casos. Por ejemplo;
add_action('pre_get_posts', 'my_function_name');
function my_function_name($query) {
if (!is_admin()) {
// Do your stuff
}
}Debido a que el enlace pre_get_postsse ejecuta tanto en el administrador como en la interfaz, podemos usar una etiqueta condicional para garantizar que nuestro código solo afecte la consulta de la interfaz.
Creando tus propios ganchos
Puede definir sus propias acciones y filtros. Si usted es un desarrollador de temas o complementos, le recomendamos que lo haga para permitir que otros modifiquen su código sin cambiar el código fuente.
Registre una acción con do_action()y registre un filtro con apply_filters().
El do_action()requiere un mínimo de 1 parámetro; el nombre del anzuelo. Tenga en cuenta que el nombre del enlace debe ser único (no lo llame, por ejemplo, initya que este es un enlace central de WordPress). Coloque el lugar do_action()donde desee que aparezca el gancho. Por ejemplo, puede colocar el gancho en el header.php, justo después del cuerpo de su tema para definir un gancho donde los desarrolladores pueden generar scripts u otro contenido.
Puede agregar tantos parámetros do_actioncomo desee después del nombre del gancho. Trate de tener en cuenta qué datos necesitarían los desarrolladores en sus ganchos, que de otro modo no serían fácilmente accesibles.
El apply_filters()requiere un mínimo de 2 parámetros; el nombre del enlace y la variable en la que está registrando el filtro. Por ejemplo, su tema puede registrar un filtro alrededor de algunas clases HTML para permitir que los desarrolladores las modifiquen o agreguen:
Al igual que con las acciones, puede agregar tantos parámetros apply_filterscomo desee después de los dos parámetros obligatorios.
Conclusión y recursos útiles
Con esto, espero que haya logrado una comprensión sólida de cómo WordPress ejecuta la mayor parte de su código, cómo puede modificar el código y cómo usted, como desarrollador, puede permitir que otros desarrolladores también realicen modificaciones en su código.