Uso y extensión de la API de correo de Drupal 8 Parte 1

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 usarlo programáticamente para enviar correos electrónicos y cómo extenderlo para usar un servicio externo como Mandrill.

Para demostrarlo, en la primera parte crearemos un correo electrónico personalizado. modelo que se usa para enviar correos electrónicos al usuario actual cuando guarda un nuevo nodo de artículo. Además, veremos cómo otros pueden alterar eso. modelo para permitir la representación HTML del cuerpo del correo electrónico en lugar del texto sin formato predeterminado.

En la segunda parte, veremos cómo ampliar el sistema de correo e integrar una API externa para la entrega de correo electrónico. Para esto, usaremos Mandrill y su biblioteca PHP que proporciona una buena base para interactuar con su API.

Todo el trabajo que realizamos se puede encontrar en este repositorio Git como parte de un módulo personalizado de Drupal 8 que comenzaremos a escribir aquí. Así que siéntase libre de revisar eso si quiere seguirlo. Empecemos.

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

d8mail.info.yml:

Nombre: Drupal 8 Descripción de Mailer: 'Demuestra el uso de la API de correo en Drupal 8.' núcleo: 8.x tipo: módulo 

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

¿Cómo enviamos un correo electrónico??

Hay dos pasos principales necesarios para enviar un correo electrónico programáticamente con Drupal 8. Primero necesitamos implementar hook_mail () para definir uno o más correos electrónicos plantillas. El segundo paso es usar el administrador de correo para enviar correos electrónicos usando uno de estos plantillas.

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

d8mail.module:

/ ** * Implementa hook_mail (). * / function d8mail_mail ($ key, & $ message, $ params) $ options = array ('langcode' => $ message ['langcode'],); switch ($ key) caso 'node_insert': $ message ['from'] = \ Drupal :: config ('system.site') -> get ('mail'); $ message ['subject'] = t ('Nodo creado: @title', array ('@ title' => $ params ['node_title']), $ options); $ message ['body'] [] = SafeMarkup :: checkPlain ($ params ['message']); descanso;  

Esta es una implementación muy simple que define uno. modelo identificado como node_insert (la $ clave). Los otros dos argumentos de función son:

• $ mensaje: aprobado por referencia, y dentro del cual agregamos la cantidad de información sobre nuestro correo electrónico que necesitamos 
• $ params: un conjunto de datos adicionales que debe ir en el correo electrónico y que se pasa del administrador de correo cuando intentamos enviar el correo electrónico

Como puedes ver, estamos construyendo el $ mensaje matriz con los valores que queremos que este correo electrónico incluya en todas las llamadas. Estamos configurando un valor predeterminado desde valor que se recupera del sistema de configuración y que representa la dirección de correo electrónico del sitio principal. Colocamos un correo electrónico tema que permite al destinatario saber que se creó un nuevo nodo, seguido del nombre del nodo (que se transmitirá a través de la $ params formación). El tema también se puede traducir al idioma que se transmite desde la persona que llama.. 

Por último, corremos el mensaje. cuerpo a través de la cadena sanitizadora porque el texto puede contener HTML y se puede truncar si no codificamos los elementos HTML. Y ya que estamos usando el SafeMarkup clase, necesitamos utilizar en la parte superior:

use Drupal \ Component \ Utility \ SafeMarkup; 

Además, el cuerpo del mensaje es una matriz que luego será implosionado 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 por el hook_mail () implementación. Ahora pasemos al código que se ejecuta cada vez que se crea un nuevo nodo, hook_entity_insert ():

/ ** * Implementa hook_entity_insert (). * / function d8mail_entity_insert (entidad Drupal \ Core \ Entity \ EntityInterface $) if ($ entity-> getEntityTypeId ()! == 'node' || ($ entity-> getEntityTypeId () === 'node' && $ entity -> bundle ()! == 'article')) return;  $ mailManager = \ Drupal :: service ('plugin.manager.mail'); $ module = 'd8mail'; $ key = 'node_insert'; $ to = \ Drupal :: currentUser () -> getEmail (); $ params ['mensaje'] = $ entidad-> obtener ('cuerpo') -> valor; $ params ['node_title'] = $ entity-> label (); $ langcode = \ Drupal :: currentUser () -> getPreferredLangcode (); $ enviar = verdadero; $ result = $ mailManager-> mail ($ module, $ key, $ to, $ langcode, $ params, NULL, $ send); if ($ result ['result']! == true) $ message = t ('Hubo un problema al enviar su notificación por correo electrónico a @email para crear el nodo @id.', array ('@ email' => $ a , '@id' => $ entity-> id ())); drupal_set_message ($ mensaje, 'error'); \ Drupal :: logger ('d8mail') -> error ($ mensaje); regreso;  $ message = t ('Se ha enviado una notificación de correo electrónico a @email para crear el nodo @id.', array ('@ correo electrónico' => $ a, '@id' => $ entidad-> id ())) ; drupal_set_message ($ mensaje); \ Drupal :: logger ('d8mail') -> aviso ($ mensaje);  

Este gancho se activa después de cada guardado de 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 verificar que la entidad del nodo es del tipo artículo, cargamos el servicio del administrador de correo de Drupal y comenzamos 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 modelo (Lo que mencioné arriba)
• la modelo id (el $ clave)
• la dirección de correo electrónico del destinatario (la que se encuentra en la cuenta de usuario actual)
• el idioma ($ langcode) que va dentro del $ params matriz y que se utilizará para traducir el mensaje del 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 del cuerpo del nodo
• el valor booleano que indica si el correo electrónico debe enviarse realmente

Luego pasamos todos estos valores a la correo() Método del gestor de correo. Este último es responsable de construir el correo electrónico (llamando al derecho hook_mail () la implementación es un aspecto de esto) y, finalmente, delegar la entrega real al complemento responsable. Por defecto, este será PHPMail, que usa el predeterminado correo() Función que viene con PHP.

Si el administrador de correo tiene éxito en enviar el correo electrónico (la entrega real no se tiene en cuenta, sino una acción de PHP exitosa), el correo() método devolverá una matriz que contiene una resultado clave con lo que devuelve el complemento de correo. Al verificar ese valor, podemos saber si la acción de correo electrónico fue exitosa e informar al usuario que le hemos notificado de su acción. De lo contrario, imprimimos y registramos un mensaje de error..

Y eso es todo. El borrado de la memoria caché y la creación de un nodo de artículo deben enviar un correo electrónico a su bandeja de entrada. Si no recibe nada y no hay signos de error en su pantalla, asegúrese de revisar los registros de su servidor y la cola de correo para verificar que se estén enviando correos electrónicos.

Antes de continuar, me gustaría hacer una nota rápida con respecto a esta implementación de gancho. En este ejemplo, coloqué toda la lógica dentro de él directamente. Además, utilicé un retorno temprano en la parte superior, lo que esencialmente significa que no se puede agregar 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 aplazar a eso. Además, no debe usar las devoluciones anticipadas dentro de las implementaciones de gancho, sino que debe 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 otra herramienta a nuestra disposición que nos permite modificar dicha configuración existente: hook_mail_alter (). Este gancho se llama desde el administrador de correo antes de que el complemento de correo responsable envíe el correo electrónico. El propósito es permitir que otros módulos realicen modificaciones finales a un correo electrónico existente que se envía.

Aunque esto también puede ser usado por otros módulos, ilustraremos una implementación de ejemplo dentro del mismo módulo con el que hemos estado trabajando. Con este fin, alteraremos 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:

/ ** * Implementa hook_mail_alter (). * / function d8mail_mail_alter (& $ message) switch ($ message ['key']) case 'node_insert': $ message ['headers'] ['Content-Type'] = 'text / html; conjunto de caracteres = UTF-8; formato = fluyó; delsp = yes '; descanso;  

Como puedes ver, esta es una simple alteración de la Tipo de contenido Encabezado 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 al usar el conmutador, nos aseguramos de que esto solo suceda con el correo electrónico. modelo definimos anteriormente.

Una cosa a tener en cuenta aquí es que se llama al enganche alter después del relevante hook_mail () implementación. Entonces, después de esto, el único procesamiento que ocurre en el correo electrónico se realiza dentro del formato() Método del complemento de correo (ejecutado por su interfaz).

Conclusión

Y eso es todo lo que hay para enviar correos electrónicos mediante Drupal 8. Programado. Hemos visto los pasos necesarios para configurar el correo electrónico mediante programación. plantillas que se hidratan por el gestor de correo cuando lo deseemos. También mencionamos el complemento de envío de correo predeterminado que se usa 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 agregando nuevos encabezados, cambiando el tema, concatenando valores al cuerpo del correo. , etc.

En el siguiente artículo, veremos cómo reemplazar el complemento predeterminado de PHPMail con nuestra propia implementación personalizada. Configuraremos un anuncio de correo que use Mandrill con la ayuda de su biblioteca de PHP. El objetivo es permitir que nuestro propio módulo use este programa de correo mientras que el resto de la aplicación continúa usando el PHPMailer predeterminado..