Hook, gancho

Te han encargado cambiar cierta funcionalidad de WordPress y no tienes ni idea de por dónde empezar. ¡Menudo marrón! Te has descargado el código fuente y encuentras un montón de archivos en PHP. Y tu primera intención como programador es encontrar dónde tienes que empezar a meter código para hacer lo que te han pedido. Primer error grave: jamás modifiques el código fuente de WordPress. En serio, no lo hagas. La solución está en los WordPress Hooks.

Cómo ya sabes, o seguramente intuyes, WordPress se encarga de construir las páginas web HTML que puedes ver en tu navegador desde el servidor. Cuando llega una petición, se inicia el Loop de WordPress. Si quieres modificar estilos, tendrás que añadir código CSS en los archivos de tu tema, pero si necesitas cambios estructurales más contundentes tendrás que ir al código fuente.

Modificando el código fuente de WordPress
Este eres tú, modificando el código fuente de WordPress.

Modificar las líneas de código del núcleo de WordPress puede parecer acertado, pero ni mucho menos lo es. Primero porque puedes romper muchas cosas, y segundo porque cuando actualizes a una nueva versión perderás los cambios muy posiblemente, porque los archivos del core se sobrescriben. Y además, ya sabemos que no actualizar es una muy mala idea.

Afortunadamente, los WordPress Hooks son un mecanismo que nos van a permitir modificar el código fuente de WordPress sin realmente tocarlo. ¿Parece algo imposible? Vas a ver que no. Permíteme que te lo demuestre.

¿Qué son los WordPress Hooks?

Simplificando al máximo, los Hooks de WordPress son puntos concretos dentro del código fuente de WordPress donde podemos conectar nuestras propias funciones para modificar ciertos contenidos o comportamientos.

Como ya ves, la palabra hook puede traducirse como gancho, y en el caso que estamos tratando, estos ganchos nos permiten colgar funciones de ellos, como si se tratase de un abrigo en una percha. Al colgar (o enganchar) nuestras funciones en un hook (o gancho), cuando la ejecución de WordPress llegue a ese hook, nuestra función se ejecutará, haciendo lo que nosotros hayamos programado.

Action Hooks y Filter Hooks

Existen dos tipos diferentes de hooks en WordPress: las acciones y los filtros. Aunque ambos son conceptos muy parecidos en cuanto a la forma de usarlos, su comportamiento es diferente.

Las acciones (o Action Hooks) nos permiten ejecutar funciones propias, además de las funciones que ya se incluyen en el código de WordPress para tal acción. Los filtros, en cambio, nos permiten modificar una funcionalidad existente. Básicamente podemos ver a las acciones y filtros como eventos concretos que al suceder llaman a las funciones nuestras que les hayamos asociado.

La principal diferencia entre acciones y filtros es que los filtros deben retornar un parámetro a la función original. Esto significa que toman un parámetro del código sobre el que filtran, lo modifican de algún modo y lo devuelven cambiado.

Por otro lado, las acciones simplemente añaden código adicional al punto donde se enganchan, sin tener en cuenta qué más se está haciendo en ese punto.

Por ejemplo, si queremos cambiar el texto de una entrada, podemos añadir una función propia a la acción publish_post (la tienes aquí en el Codex) que modifique la entrada en el momento de publicarla. O podemos añadir una función en el filtro the_content (aquí en el Codex) que modifique la entrada cuando se está a punto de pintar en el navegador del visitante.

No te preocupes si aún tienes dudas entre acciones y filtros, seguramente se despejen cuando veas el código.

Nelio Unlocker

Pásate a WordPress manteniendo tus diseños y contenidos

Mejora hoy mismo el SEO de tu web y acelera su velocidad de carga convirtiendo tus páginas a estándares HTML, CSS y WordPress. No necesitas conocimientos técnicos y solo pagarás por aquello que necesites.

La estructura de un hook

Para definir una función y engancharla en un hook de WordPress, sólo hemos de definir la función y utilizar la llamada add_action o add_filter, como vemos a continuación:

Ten en cuenta que add_action la utilizamos cuando queremos engancharnos a un Action Hook, mientras que add_filter cuando queremos engancharnos a un Filter Hook. Sin embargo, add_filter no es más que un alias a add_action (internamente hace una llamada a add_action), por lo que podríamos usar siempre add_action y no pasaría nada.

Veamos los parámetros que admite la función add_action para definir el enganchamiento de tu función de un hook de WordPress concreto (ver línea 5 del código anterior):

  • nombre_del_hook: El nombre de la acción o filtro concreto de WordPress, e indica a qué evento asociar nuestra función.
  • mi_funcion: El nombre de la función que queremos asociar con el hook concreto. Puede ser una función estándar de PHP, una función existente en el código fuente de WordPress, o una función que nosotros definamos (como sucede en el ejemplo anterior, líneas 2 a 4).
  • prioridad: Es un parámetro opcional utilizado para especificar el orden en el que la función asociada al hook se va a ejecutar. Es un valor entero (un número, vaya) y por defecto si no ponemos nada tiene un valor de 10. Indicar un número más bajo indica que queremos que nuestra función sea más prioritaria que otras. Si hay más de una función asociada a un hook concreto y tienen la misma prioridad, se ejecutan en el orden en el que se hayan añadido al hook.
  • parametros: Es un parámetro opcional cuyo valor es un entero (otro número) que indica cuántos parámetros ha de aceptar la función que asociamos al hook. Por defecto el valor es 1, aunque hay algunos hooks que pueden pasar más de una parámetro a la función.

Como lo mejor es ver ejemplos, vamos a empezar por añadir una función que envíe un correo al autor de una entrada cuando esta se publica en nuestro WordPress. Utilizamos la Action Hook publish_post que ya hemos mencionado antes y la función wp_mail que puedes ver aquí en el Codex:

Fíjate que asociamos la función notifica_al_autor al Action Hook publish_post mediante add_action. La función que hemos enganchado lo único que hace es una llamada a wp_mail para enviar un correo al autor de la entrada.

Y ahora vamos a ver un ejemplo de filtro:

Como puedes intuir mirando el código, utilizamos el filtro the_title que nos permite modificar el título de entradas cuando las devolvemos desde la base de datos de WordPress. En este caso enganchamos al filtro una función nuestra cuyo nombre es incluye_exclusiva que añade el texto "¡Exclusiva!" delante de un título cuando la entrada pertenece a la categoría Exclusiva.

De este modo, hemos visto dos ejemplos de cómo modificar el comportamiento por defecto de WordPress sin tener que que tocar el código fuente del propio WordPress. La pregunta que seguramente te estarás haciendo es: si no puedo tocar el código fuente, ¿dónde he de poner el código de los hooks que hemos visto en los ejemplos para que funcione? Sigue leyendo para saber la respuesta.

Cómo implementar WordPress Hooks

Hay varias maneras de añadir código que implementa funciones asociadas a hooks en WordPress. Principalmente, podemos añadir este código dentro del archivo functions.php de tu tema, o incluso mejor, dentro de un tema hijo. De este modo tus funciones estarán disponibles para ser ejecutadas.

Otra opción es crear un plugin nuevo dónde incluir estas funciones junto a las llamadas a add_filter y add_action. Esto puede ser algo más complicado, si no sabemos trabajar con plugins, por lo que te recomiendo empezar con el archivo functions.php. Tan sólo hemos de ir a Apariencia » Editor dentro del Escritorio de WordPress y ahí escoger el tema que tenemos activo. Buscamos el archivo functions.php y añadimos el código que queramos, siguiendo las directrices explicadas en la sección anterior.

Tienes que tener un par de cosas en cuenta cuando hagas esto. La primera es no equivocarte con la sintaxis PHP, ya que si escribes mal el código puedes tirar por los suelos toda tu web. Lo mejor para ello es bajarte por FTP el archivo functions.php a tu ordenador, guardar una copia sin ninguna modificación (por si acaso) y editar una copia en local. Cuando hayas acabado y estés seguro que está bien, súbelo de nuevo por FTP y comprueba que todo funciona bien. Si te hubieras equivocado y tu web no funciona, no pasa nada; vuelve a subir la copia original del archivo.

La otra cosa a tener en cuenta es que el nombre de la función que asocies a un hook ha de ser único. Si utilizas un nombre que otro plugin o tema ya utilice, tendrás problemas. Por lo que suele estar bien añadir un prefijo antes del nombre de la función. Por ejemplo, en la función anterior incluye_exclusiva podríamos usar mejor wprincipiante_incluye_exclusiva, ya que seguramente nadie más a parte de nosotros utilizará nombres de función que empiecen por wprincipiante_.

Por último, si queremos desactivar una acción o un filtro sólo tenemos que llamar a las funciones remove_action o remove_filter:

En el ejemplo anterior vemos cómo desactivar la asociación entre los hooks y las funciones de los ejemplos que hemos visto antes. Y si quieres volver a activar una función que hayamos desactivado, tan solo has de volver a hacer al llamada a add_action o add_filter. Tan simple como eso.

Solo un apunte más para terminar. Si al usar add_action o add_filter indicaste una prioridad diferente del valor por defecto de 10, al hacer remove_action o remove_filter tendrás que especificar el valor concreto para que la desactivación funcione. Y recuerda no eliminar nada a menos que estés seguro de lo que estás haciendo.

Para saber más

Este artículo no es más que una introducción básica a los hooks en WordPress. Si quieres entrar en más detalle en ciertos aspectos, debes visitar el Codex de WordPress, donde encontrarás todo lo necesario para convertirte en un crack del desarrollo.

En concreto, deberías echarle un ojo a las siguientes secciones del Codex:

  • Filter Reference: Lista con todos los Filter Hooks (o filtros) que están disponibles en WordPress.
  • Action Reference: Lista con todos los Action Hooks (o acciones) disponibles.
  • Plugin API: Introducción a los hooks en WordPress desde la perspectiva del desarrollo de plugins.
  • Theme Development: Introducción al desarrollo de temas para WordPress.
  • Writing a Plugin: Introducción al desarrollo de plugins en WordPress.

Resumen final

En esta entrada has conocido los WordPress Hooks, y en concreto las acciones y filtros que nos permiten modificar el comportamiento de WordPress sin tener que cambiar el código fuente.

Tanto si piensas desarrollar o modificar temas de WordPress o si quieres crear plugins, los WordPress Hooks son los ganchos que te van a permitir añadir código propio (engancharte) a ciertos puntos de la ejecución de WordPress, así como filtrar ciertos datos para modificar sus valores.

Además de ver cómo implementar hooks incluyendo nuestras propias funciones PHP, hemos visto cómo desactivarlos. Al principio trabajar con ellos es un poco liado, pero a la larga todo es mucho más dinámico.

Para terminar sólo me queda repetir que no toques el código fuente de WordPress directamente, sino que uses los Hooks. Y si tienes dudas, siempre las puedes describir en los comentarios, donde intentaremos ayudarte a resolverlas.

Imagen destacada de haru__q.

28 respuestas a «WordPress Hooks – Guía para principiantes»

  1. Avatar de Dokues
    Dokues

    Buen artículo. Gracias

  2. Avatar de Amanda
    Amanda

    Buenas, me ha gustado mucho tu artículo y me ha ayudado a entender mejor los hooks. Ya que soy algo novata y todo esto de golpe me viene grande. Quiero crear un botón que cuando se le de genere un cuestionario online en PDF, tengo el código de generar en PDF y el del botón pero no sé como unirlo y me han recomendado un hook pero sigo sin saber como integrarlo en wordpres ni nada. Si pudieras ayudarme, gracias.

    1. Avatar de Nelio

      Hola Amanda. Primero de todo, gracias por tu apoyo. Sobre lo que comentas, necesitaríamos tener más detalles de lo que quieres hacer. Así a bote pronto, si tienes un botón y quieres enlazarlo con un código, deberías utilizar el evento onclick. No obstante, como ya te digo, puede que esto te sirva o no dependiendo de qué quieres hacer y cómo tienes tanto el botón como el código para generar el PDF.

      ¡Un saludo!

      1. Avatar de Amanda
        Amanda

        Lo que no se es como llamar en la opción onclick a mi función, que pongo onclick=nombreFunción(), soy bastante novata en la programación de este tipo y en internet no encuentro mucha información. Gracias.

        1. Avatar de Antonio Villegas

          Si tu función es JavaScript y la tienes accesible desde el HTML (la has importado o está incrustada en el HTML directamente con una etiqueta ), esa es la manera de ejecutarla cuando pulsas el botón. De todas formas, mi consejo es que deberías empezar con tutoriales que encuentres por Internet sobre JavaScript básico y tal (hay miles). ¡Muchos ánimos!

  3. Avatar de Héctor J. Orihuela
    Héctor J. Orihuela

    Buenas Antonio, he de felicitarte por lo ameno pero aclarador que ha sido tu post.

    Soy desarrollador de aplicaciones (sobre todo web) y he trabajado con CodeIgniter para PHP y con MVC de ASP.NET (actualmente). La cuestión es que me he dado cuenta de que wordpress es una gran herramienta (ya que te da muchas cosas ya hechas) si sabes utilizarlo bien.

    En cuestiones de programación no tengo problemas, y de hecho todo lo que quiero modificar me gustaría hacerlo con código, los ‘hooks’ son según tu artículo la solución.

    La cuestión y es por ello que te escribo, es que ando bastante perdido en todo el tema de wordpress, ya que comprendo que con eso se podría modificar el comportamiento de cualquier plugin o de cualquier sección de wordpress, pero… cómo podría cambiar el aspecto por completo? la estructura? Por ejemplo poner los menús laterales en vez de en el top?

    Por lo tanto, me gustaría saber si es posible que me indicases algún libro o documental / tutorial donde pudiese aprender a manejar y modificar todo lo anteriormente comentado.

    Gracias de antemano por todo!! Saludos!

    1. Avatar de David Aguilera

      Buenos días, Héctor.

      En primer lugar, muchas gracias por leernos y por participar 🙂 En cuanto a tus dudas, te recomiendo que eches un vistazo a la propia documentación de WordPress; tienen un apartado con mucha información sobre la creación de temas (que, entiendo, es lo que te interesa ahora mismo), donde explican cómo funcionan y se organizan los temas de WordPress. Finalmente, otro consejo: si vas a crear temas, no te tires a lo loco y empieces de cero; basa tu trabajo en alguno ya existente, como por ejemplo underscores.

  4. Avatar de Héctor J. Orihuela
    Héctor J. Orihuela

    Buenas Antonio, antes de nada felicitarte por el post, ya que lo explicas de una forma amena y clara.

    La cuestión es que estoy empezando con WordPress a nivel de desarrollo, siempre he trabajado con CodeIgniter para PHP y con MVC ASP.NET C# en mi actual trabajo.

    Podrías recomendarme algún libro o página donde se dé una visión global de todo lo que es WordPress para desarrolladores y cómo modificar todo, a lo cual me surge la duda de si en WordPress con los Hooks puedo modificar cualquier cosa, incluso la estructura básica (que imagino que no).

    Gracias de antemano por la ayuda, saludos!!

    1. Avatar de David Aguilera

      Buenas de nuevo, Héctor.

      Como te comentaba en el comentario anterior, si lo que quieres es cambiar completamente el aspecto de WordPress, lo que debes hacer es crear tu propio tema. Si lo haces bien, podrás usar cualquier distribución de contenido (menús superiores, laterales, sin menús, organización a x columnas, tipos de letra… lo que quieras).

      Si todavía tienes alguna duda más, no dudes en volver a preguntarnos.

      Un saludo,
      David

      1. Avatar de Héctor J. Orihuela
        Héctor J. Orihuela

        Buenos días / tardes David.

        Antes de nada disculparme por el doble post, pero pensaba que no se había enviado el primero (luego caí en la cuenta de que necesitaba tu aprobación jeje).

        Estoy mirando los enlaces que me has pasado, parece ser que es lo que busco. Seguiré investigando y dentro de un tiempo volveré para comentarte qué tal me fue.

        Te agradezco tu ayuda, tiempo y dedicación. Saludos!

        1. Avatar de David Aguilera

          No hay problema 🙂 Quedamos, pues, a la espera de saber qué tal ha ido 😉

  5. Avatar de Alf

    Al fin me entero para que sirve todo esto, muchas gracias!

  6. Avatar de Luigi José Díaz Flores
    Luigi José Díaz Flores

    Buenas tardes.

    Excelente post, de verdad que muy claro. Muchas gracias por ello. Me estoy iniciando en WordPress y mi pregunta es si conoces algún tutorial de como hacerlo en WordPress.

    Muchas gracias.

    1. Avatar de Antonio Villegas

      Hola Luigi José. Puedes encontrar muchos tutoriales sobre los hooks en WordPress, incluso este que has leído es uno de ellos. Si quieres también aprender sobre el loop de WordPress tienes este artículo, que es el primero de una serie de 3 dónde aprender a dominar WP_Query. Por último, como referencia oficial tienes el Codex. ¡Mucha suerte!

  7. Avatar de Marcela
    Marcela

    Buenas Tardes,

    Estoy intentando realizar un buscador personalizado, es decir que me pueda buscar dentro de una misma pagina por los filtro de ciudad y titulo. Ciudad es un campo personalizado que he creado. ¿quisiera saber si es posible con el tema de los hooks y q funciones deberia usar para realizarlo?

    Gracias

    1. Avatar de Antonio Villegas

      Puedes mirarte la documentación de WordPress para crear un buscador aquí y luego ver cómo modificar la WP_QUery para que busque los contenidos que quieres. Otra opción es usar un plugin como Relevanssi, que te permite extender el funcionamiento del campo de búsqueda de WordPress por defecto.

  8. Avatar de Francisco José
    Francisco José

    Buenas tardes Antonio, excelente artículo.

    Me estoy iniciando en WordPress y en php y tengo muy pocos conocimientos de ambos. Estoy haciendo mi primer hook y función en mi página de wordpress. Mi idea es que un usuario, cuando finalice la compra de un artículo en Woocommerce (no antes de ello), pueda acceder a publicar un post. Estoy loco con este código, no veo el fallo, de hecho no da fallo alguno, pero tampoco hace ningún efecto. No tengo muy claro si necesitaría el hook de finalizar la compra o el de publish post, en este código uso ambos. ¿Podría ayudarme? Se lo agradecería muchísimo

    Saludos y enhorabuena por el artículo.

    function so_payment_complete( $order_id ){

    $order = wc_get_order( $order_id );
    $user = $order->get_user();

    function publicar( $order_id ){

    $order = wc_get_order( $order_id );
    $user = $order->get_user();

    if( isset($user) ){
    $user->add_cap( ‘publish_post’ );

    }

    }
    }

    add_action( ‘woocommerce_payment_complete’, ‘so_payment_complete’ );
    add_action( ‘publish_post’, ‘publicar’ );

    1. Avatar de Antonio Villegas

      Hola Francisco José. Estoy viendo tu código y hay bastante lío. Si quieres darle permisos al usuario que compra, no necesitas usar el hook de publish_post. De hecho, estaría mejor hacer hook a ‘woocommerce_order_status_completed’ en vez de a ‘woocommerce_payment_complete’.

      Con todo esto, y sin probarlo, podrías hacer algo tal que así:

      function so_payment_complete( $order_id ){
      $order = wc_get_order( $order_id );
      $user = $order->get_user();
      if( isset( $user ) ) {
      $user->add_cap( ‘publish_post’ );
      }
      }
      add_action( ‘woocommerce_order_status_completed’, ‘so_payment_complete’ );

      Como te digo, no lo he probado, pero tiene mejor pinta que lo que planteabas inicialmente (vigila, porque definías una función dentro de otra). ¡Ánimo con el aprendizaje!

  9. Avatar de Aitor

    Hola gran aporte, una duda, si quiero hacer un hook para que si sucede una cosa elimine el hook que ha añadido ahí un fragmento de texto como puedo hacerlo?

    1. Avatar de Antonio Villegas

      Hola Aitor. No acabo de entender bien qué es lo que necesitas. Estaría bien que me explicaras qué quieres decir con «ahí» y con fragmento de texto.

  10. Avatar de rPeter

    Hola @Antonio soy rPeter y os agradezco a tí a tus compañeros la labor que habéis hecho creando estos pedazos de POST.

    Soy programador en varios niveles tanto backend como frontend y en varias tecnologías, frameworks y me he propuesto aprender sobre la creación de plugins para el CMS WordPress, sin lugar a dudas al haber leído este thread se me ha quedado un buen sabor de boca.

    Me habéis hecho comprender de forma fácil los hooks y como interaccionar con ellos , por eso como no daros mi más enhorabuena y bendición.

    Un abrazo cordial de rPeter.

    1. Avatar de David Aguilera

      ¡Muchísimas gracias por tus palabras! Es un placer y una satisfacción saber que nuestros artículos os gustan y ayudan.

  11. Avatar de Antonio

    Magnífico, Antonio…
    Pedazo de introducción a los hooks de WordPress…
    Con personas como tu da gusto buscar tutoriales y contenido…
    Muchas gracias…!!!

    1. Avatar de David Aguilera

      Gracias, Antonio. Nuestro Antonio está esta semana de vacaciones, pero con lectores como tú seguro que vuelve con ganas de seguir escribiendo 😉

  12. Avatar de Andri
    Andri

    Saludos buen post, sobre todo para comenzar a echar un poco a modificar la forma como queremos que wordpress nos presente la información.
    una consulta:
    Tengo un WP con woocommerce y el aplicativo para multi-vendedores, la cosa es que quiero que el buscar me muestre en ves de los artículos los vendedores que tienen ese articulo.
    Si hay un plugin que lo haga o si hay una forma de hacerlo con hooks y me puedes ilustrar

    1. Avatar de Antonio Villegas

      Hola Andri. Gracias por tu comentario. Respecto al problema que comentas, sin ponerme a mirarlo con más profundidad no sé la respuesta concreta. Sin embargo, te animo a que te pongas en contacto con el soporte de WooCommerce para que te ayuden. Un saludo.

  13. Avatar de asbel leon
    asbel leon

    me encanto mucho y más cuando escribistes que no hay que tocar el codigo de los archivos , pues es lo que yo solia hacer, pero esto del hook esta impresionante , muchas gracias de verdad. mi duda es ¿Cómo puedo hacer para llamar una action de un plugin para hacer una funcionalidad especifica? ejemplo: que cuando el usuario este registrado y quiera darle clic en «me gusta» pulgarcito arriba , entonces le despliegue un mensaje de que espere ser aprobado por el administrador del sistema. saludos y gracias espero me puedas responder mi msj.

    1. Avatar de Antonio Villegas

      Gracias por el comentario. Primero, lo que necesitas es saber si la action existe en ese plugin como para meter tu código. Si está preparado, tendrás que encontrar esa action en el código o en la documentación de dicho plugin para saber qué parámetros te pasan y tal.

Deja una respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

He leído y acepto la política de privacidad de Nelio Software

Tus datos personales se almacenarán en SiteGround y serán usados por Nelio Software con el único objetivo de publicar tu comentario aquí. Con el envío de este comentario, nos das el consentimiento expreso para ello. Escríbenos para acceder, rectificar, limitar o eliminar tus datos personales.