Unlimited Plugins, WordPress themes, videos & courses! Unlimited asset downloads! From $16.50/m
Advertisement
  1. Code
  2. Drupal

Uso y extension de la API de Drupal 8 Mail: Parte 1

by
Difficulty:IntermediateLength:MediumLanguages:
This post is part of a series called Using and Extending the Drupal 8 Mail API.
Using and Extending the Drupal 8 Mail API: Part 2

Spanish (Español) translation by Elías Nicolás (you can also view the original English article)

En esta serie de dos partes vamos a explorar la API de correo en Drupal 8. Al hacerlo, vamos a cubrir dos aspectos principales: cómo utilizarlo de forma programática para enviar correos electrónicos y cómo extenderlo para usar un servicio externo como Mandrill .

Para demostrar esto, en la primera parte crearemos una plantilla de correo electrónico personalizada que se utilizará para enviar correos electrónicos al usuario actual cuando salve un nuevo nodo Artículo. Además, veremos cómo otros pueden alterar esa plantilla para permitir la representación HTML del cuerpo del correo electrónico en lugar del texto normal predeterminado.

En la segunda parte vamos a ver ampliar el sistema de correo e integrar una API externa para la entrega de correo electrónico. Para ello, utilizaremos Mandrill y su biblioteca PHP que proporciona una buena base para interactuar con su API.

Todo el trabajo que vamos a través de se puede encontrar en este repositorio de Git como parte de un módulo de Drupal 8 personalizado que vamos a empezar a escribir aquí. Así que siéntase libre de comprobar que si quieres seguir adelante. Empecemos.

El primer requisito previo de este módulo es su archivo .info:

d8mail.info.yml:

Con esto fuera del camino, ya podemos habilitar el módulo en nuestro sitio si lo deseamos.

¿Cómo enviamos un correo electrónico?

Hay dos pasos principales necesarios para enviar un correo programáticamente con Drupal 8. En primer lugar debemos implementar hook_mail() para definir una o más plantillas de correo electrónico. El segundo paso es utilizar el administrador de correo para enviar correos electrónicos utilizando una de estas plantillas.

Aunque se llama hook, hook_mail() no es un gancho típico, sino más bien una función regular que generalmente se llama sólo por el mismo módulo que lo implementa. En otras palabras, cuando envía un correo programáticamente, debe especificar el nombre del módulo que implementa hook_mail() y el ID de la plantilla que desea usar y que está definido por este gancho. Pero lo veremos en un minuto. Primero, ¿cómo lo implementamos?

d8mail.module:

Esta es una implementación muy sencilla que define una plantilla identificada como node_insert (el $key). Los otros dos argumentos de función son:

  • $message: se pasa por referencia, y dentro de la cual agregamos tanto boilerplate sobre nuestro correo electrónico como necesitamos
  • $params: una matriz de datos extra que necesita ir en el correo electrónico y que se pasa desde el administrador de correo cuando tratamos de enviar el correo electrónico

Como puede ver, estamos construyendo la matriz $message con valores que queremos que este correo electrónico incluya en todas las llamadas. Estamos estableciendo un valor predeterminado del valor from que se recupera del sistema de configuración y que representa la dirección de correo electrónico principal del sitio. Establecemos un subject de correo electrónico que permite al destinatario saber que se ha creado un nuevo nodo, seguido del nombre del nodo (que se pasará a través de la matriz $params). El tema también es traducible a el idioma que se pasa de la persona que lo enviá.

Por último, ejecutamos el mensaje body a través del sanitizador de cadena porque el texto puede contener HTML y podría quedar truncado si no codificamos los elementos HTML. Y como estamos utilizando la clase SafeMarkup, necesitamos usarla en la parte superior:

Además, el cuerpo del mensaje es una matriz que posteriormente se implosionará en una cadena. Y, obviamente, hay muchos otros parámetros que podemos establecer, como los encabezados, pero esto será suficiente para este ejemplo.

Y eso es todo para la implementación hook_mail(). Ahora veamos el código que se ejecuta cada vez que se crea un nuevo nodo, hook_entity_insert():

Este gancho se dispara después de guardar cada nodo, y todo lo que tenemos que hacer es asegurarnos de que estamos apuntando al nodo correcto e incluir nuestra lógica.

Después de comprobar que la entidad de nodo es del tipo  article, cargamos el servicio de administrador de correo de Drupal y empezamos a configurar algunos valores para el correo electrónico. Necesitamos la siguiente información:

  • El nombre del módulo que implementa hook_mail() y define nuestra plantilla (lo que he mencionado anteriormente)
  • El ID de plantilla (la $key)
  • La dirección de correo electrónico del destinatario (la que se encuentra en la cuenta de usuario actual)
  • El lenguaje ($langcode) que va dentro de la matriz $params y que se usará para traducir el mensaje de asunto
  • El título del nodo que se agregará al asunto del correo electrónico
  • El cuerpo del correo electrónico, que en nuestro caso será el valor del campo body del nodo
  • El valor booleano indica si el correo electrónico debe enviarse realmente

Luego pasamos todos estos valores al método mail() del gestor de correo. Este último es responsable de construir el correo electrónico (llamando a la correcta hook_mail() la implementación es un aspecto de esto) y finalmente delegar la entrega real al plugin responsable. De forma predeterminada, será PHPMail, que utiliza la función predeterminada de correo mail() que viene con PHP.

Si el administrador de correo tiene éxito al enviar el correo electrónico (la entrega real no se tiene en cuenta, sino una acción de PHP exitosa), el método mail() devolverá una matriz que contenga una clave result con lo que devuelva el complemento de correo. Comprobando ese valor, podemos saber si la acción del correo electrónico fue exitosa e informar al usuario que les hemos notificado de su acción. De lo contrario, mostramos y registramos un mensaje de error.

Y eso es todo. Al borrar la memoria caché y crear un nodo de artículo, debe enviar un correo electrónico a su bandeja de entrada. Si no obtiene nada y no hay signos de error en la pantalla, asegúrese de revisar los registros del servidor y la cola de correo para verificar que se envían mensajes de correo electrónico.

Antes de seguir adelante, me gustaría hacer una breve nota sobre esta implementación de gancho. En este ejemplo, coloqué toda la lógica dentro de él directamente. Además, utilicé un regreso temprano en la parte superior, lo que esencialmente significa que no se puede agregar ninguna otra lógica sino la específica de los nodos del artículo. En aplicaciones reales recomiendo refactorizar la lógica de correo en una función o clase separada y diferir a eso. Por otra parte, no debe utilizar devoluciones tempranas dentro de implementaciones de gancho, sino en lugar de llamar a otras funciones si se cumplen las condiciones.

¿Cómo alteramos un correo electrónico?

Una vez que todo esto está en su lugar, tenemos a nuestra disposición otra herramienta que nos permite modificar una configuración existente: hook_mail_alter(). Este gancho se llama desde dentro del administrador de correo antes de que el plugin de correo responsable envíe el correo electrónico. El propósito es permitir que otros módulos realicen alteraciones finales a un correo electrónico existente que se envía.

Aunque esto también puede ser utilizado por otros módulos, ilustraremos un ejemplo de implementación desde el mismo módulo con el que hemos estado trabajando. Para ello, modificaremos el correo electrónico cambiando uno de sus encabezados predeterminados para transformarlo de texto sin formato a HTML. Y así es como podemos hacer esto:

Como puede ver, se trata de una simple alteración de la cabecera Content-Type que transforma el correo electrónico en HTML. De esta manera, las entidades HTML de texto sin formato serán analizadas como HTML por los clientes de correo. Y con el caso de conmutación, nos aseguramos de que esto sólo suceda para la plantilla de correo electrónico que definimos anteriormente.

Una cosa a tener en cuenta aquí es que el gancho alter se llama después de la implementación hook_mail() relevante. Así que después de esto, el único procesamiento que sucede en el correo electrónico se realiza dentro del método format() del complemento de correo (forzado por su interfaz).

Conclusión

Y eso es prácticamente todo lo que hay para enviar mensajes de correo mediante programación utilizando Drupal 8. Hemos visto los pasos necesarios para configurar plantillas de correo electrónico que se hidratan por el administrador de correo siempre que lo desee. También hemos mencionado el complemento de entrega por correo predeterminado que se utiliza para enviar correos electrónicos en Drupal 8. Y por último, hemos visto cómo otros módulos pueden ahora alterar nuestro correo electrónico añadiendo nuevos encabezados, cambiando el asunto, concatenando valores al cuerpo del correo, etc.

En el próximo artículo vamos a buscar en reemplazar el plugin de PHPMail por defecto con nuestra propia implementación personalizada. Vamos a configurar un mailer que utiliza Mandrill con la ayuda de su biblioteca PHP. El objetivo es permitir que nuestro propio módulo utilice este mailer mientras que el resto de la aplicación continúa usando el PHPMailer predeterminado.

Advertisement
Advertisement
Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.