Extension des capacités de l'API Drupal 8 Mail : partie 1

Dans cette série en deux parties, nous explorerons l'API Mail dans Drupal 8. En cours de route, nous aborderons deux aspects principaux : comment l'utiliser par programmation pour envoyer des e-mails et comment l'étendre pour utiliser des services externes comme Mandrill.

Pour démontrer cela, dans la première partie, nous créerons un modèle d'e-mail personnalisé qui enverra un e-mail à l'utilisateur actuel lorsqu'il enregistrera un nouveau nœud d'article. De plus, nous verrons comment d'autres ont modifié ce modèle pour permettre au HTML d'afficher le corps de l'e-mail au lieu du texte brut par défaut.

Dans la deuxième partie, nous examinerons l'extension du système de messagerie et l'intégration d'API externes pour la livraison des e-mails. Pour cela nous utiliserons Mandrill et sa librairie PHP, qui constitue une bonne base pour interagir avec son API.

Tout le travail que nous avons effectué se trouve dans ce référentiel Git dans le cadre du module Drupal 8 personnalisé que nous allons commencer à écrire ici. Alors si vous souhaitez suivre, n'hésitez pas à y jeter un œil. Commençons.

Le premier prérequis pour ce module est son .info dossier :

d8mail.info.yml:

name: Drupal 8 Mailer
description: 'Demonstrates the use of the Mail API in Drupal 8.'
core: 8.x
type: module

Une fois ce problème résolu, nous pouvons activer le module sur notre site Web si nécessaire.

Comment envoyer des e-mails ?

L'envoi d'e-mails par programmation à l'aide de Drupal 8 nécessite deux étapes principales. Nous devons d'abord implémenter hook_mail() pour définir un ou plusieurs modèles d'e-mails. La deuxième étape consiste à utiliser votre gestionnaire de messagerie pour envoyer un e-mail en utilisant l'un de ces modèles.

Bien qu'appelé un hook, hook_mail() 并不是典型的钩子，而是更多的常规函数​​，通常仅由实现它的同一模块调用。换句话说，当您以编程方式发送电子邮件时，您需要指定实现 hook_mail() le nom du module et l'identifiant du template que vous souhaitez utiliser et défini par ce hook. Mais nous le verrons bientôt. Tout d’abord, comment le mettre en œuvre ?

d8mail.module:

/**
 * Implements hook_mail().
 */
function d8mail_mail($key, &$message, $params) {
  $options = array(
    'langcode' => $message['langcode'],
  );

  switch ($key) {
    case 'node_insert':
      $message['from'] = \Drupal::config('system.site')->get('mail');
      $message['subject'] = t('Node created: @title', array('@title' => $params['node_title']), $options);
      $message['body'][] = SafeMarkup::checkPlain($params['message']);
      break;
  }
}

Il s'agit d'une implémentation très simple qui définit un node_insert （$keymodèle identifié comme ). Les deux autres paramètres de la fonction sont :

• $message : Passer par référence, où nous ajoutons autant de passe-partout sur l'e-mail que nécessaire
• $params : Tableau de données supplémentaires qui doivent être insérées dans l'e-mail, transmises par le gestionnaire de messagerie lorsque nous essayons d'envoyer l'e-mail

Comme vous pouvez le voir, nous construisons un tableau $message 数组，其中包含我们希望此电子邮件包含在所有调用中的值。我们正在设置一个默认的 from 值，该值从配置系统检索并代表主站点电子邮件地址。我们设置一个样板电子邮件 subject ，让收件人知道创建了一个新节点，后跟节点的名称（将通过 $params contenant les valeurs que nous souhaitons que cet e-mail inclue dans tous les appels. Nous définissons une valeur from par défaut qui est récupérée du système de configuration et représente l'adresse e-mail du site principal. Nous avons mis en place un e-mail standard subject qui informe le destinataire qu'un nouveau nœud a été créé, suivi du nom du nœud (qui sera transmis via le tableau

). Le sujet peut également être traduit dans la langue transmise par l'appelant.

body，因为文本可能包含 HTML，如果我们不对 HTML 元素进行编码，它可能会被截断。由于我们使用的是 SafeMarkupEnfin, nous transmettons le message à travers la classe String Sanitizer , nous devons donc l'utiliser en haut

 :

use Drupal\Component\Utility\SafeMarkup;

De plus, le corps du message est un tableau, qui implosera

plus tard en une chaîne. Évidemment, nous pouvons définir de nombreux autres paramètres, tels que les en-têtes, mais cela suffit pour cet exemple.

hook_mail()C'est ce qu'est

. Regardons maintenant le code qui s'exécute à chaque fois qu'un nouveau nœud est créé, hook_entity_insert() :

/**
 * Implements hook_entity_insert().
 */
function d8mail_entity_insert(Drupal\Core\Entity\EntityInterface $entity) {

  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['message'] = $entity->get('body')->value;
  $params['node_title'] = $entity->label();
  $langcode = \Drupal::currentUser()->getPreferredLangcode();
  $send = true;

  $result = $mailManager->mail($module, $key, $to, $langcode, $params, NULL, $send);
  if ($result['result'] !== true) {
    $message = t('There was a problem sending your email notification to @email for creating node @id.', array('@email' => $to, '@id' => $entity->id()));
    drupal_set_message($message, 'error');
    \Drupal::logger('d8mail')->error($message);
    return;
  }

  $message = t('An email notification has been sent to @email for creating node @id.', array('@email' => $to, '@id' => $entity->id()));
  drupal_set_message($message);
  \Drupal::logger('d8mail')->notice($message);
}

Ce hook sera déclenché après chaque sauvegarde de nœud, tout ce que nous avons à faire est de nous assurer de cibler le bon nœud et d'inclure notre logique.

articleAprès avoir vérifié que l'entité du nœud est de type

, nous chargeons le service Drupal Mail Manager et commençons à définir certaines valeurs pour l'e-mail. Nous avons besoin des informations suivantes : 🎜

• 实现 hook_mail() 并定义我们的模板（我上面提到的）的模块名称
• 模板 ID（$key）
• 收件人电子邮件地址（在当前用户帐户中找到的地址）
• 进入 $params 数组并用于翻译主题消息的语言 ($langcode)
• 将添加到电子邮件主题的节点标题
• 电子邮件正文，在我们的例子中将是节点正文字段的值
• 指示是否应实际发送电子邮件的布尔值

然后我们将所有这些值传递给邮件管理器的 mail() 方法。后者负责构建电子邮件（调用正确的 hook_mail() 实现是其中的一方面）并最终将实际交付委托给负责的插件。默认情况下，这将是 PHPMail，它使用 PHP 自带的默认 mail() 函数。

如果邮件管理器成功发送电子邮件（不考虑实际发送，而是考虑成功的 PHP 操作），则 mail() 方法将返回一个包含 result 键的数组，其中包含以下内容：邮件插件返回。通过检查该值，我们可以了解电子邮件操作是否成功，并通知用户我们已通知他们他们的操作。否则，我们将打印并记录一条错误消息。

就是这样。清除缓存并创建文章节点应该会在您的收件箱中收到一封电子邮件。如果您没有收到任何信息，并且屏幕上没有错误迹象，请务必检查服务器日志和邮件队列，以验证电子邮件是否已发出。

在继续之前，我想快速说明一下这个钩子的实现。在这个例子中，我直接将所有逻辑放在其中。此外，我在顶部使用了早期返回，这本质上意味着除了特定于文章节点的逻辑之外，不能添加其他逻辑。在实际应用程序中，我建议将邮件逻辑重构为单独的函数或类，并遵循该逻辑。此外，您不应在钩子实现中使用提前返回，而应在满足条件时调用其他函数。

我们如何更改电子邮件？

一旦所有这些都到位，我们就可以使用另一个工具来更改现有的设置：hook_mail_alter()。在负责的邮件插件发送电子邮件之前，从邮件管理器内部调用此挂钩。目的是允许其他模块对正在发送的现有电子邮件进行最终更改。

虽然其他模块也可以使用它，但我们将在我们一直使用的同一模块中说明示例实现。为此，我们将通过更改其默认标头之一来更改电子邮件，以便将其从纯文本转换为 HTML。我们可以这样做：

/**
 * Implements hook_mail_alter().
 */
function d8mail_mail_alter(&$message) {
  switch ($message['key']) {
    case 'node_insert':
      $message['headers']['Content-Type'] = 'text/html; charset=UTF-8; format=flowed; delsp=yes';
      break;
  }
}

如您所见，这是对 Content-Type 标头的简单更改，可将电子邮件转换为 HTML。这样纯文本 HTML 实体将被邮件客户端解析为 HTML。使用 switch case，我们确保这只发生在我们之前定义的电子邮件模板中。

这里需要注意的一件事是，在相关的 hook_mail() 实现之后调用 alter hook。因此，在此之后，对电子邮件进行的唯一处理是在邮件插件的 format() 方法内完成的（由其接口强制执行）。

结论

这几乎就是使用 Drupal 8 以编程方式发送电子邮件的全部内容。我们已经了解了以编程方式设置电子邮件模板所需的步骤，只要我们需要，这些模板就会由邮件管理器进行水合。我们还提到了 Drupal 8 中用于发送电子邮件的默认邮件传递插件。最后，我们看到了其他模块现在如何通过添加新标头、更改主题、将值连接到邮件正文来更改我们的电子邮件等

在下一篇文章中，我们将考虑用我们自己的自定义实现替换默认的 PHPMail 插件。我们将在 PHP 库的帮助下设置一个使用 Mandrill 的邮件程序。目标是允许我们自己的模块使用此邮件程序，而应用程序的其余部分继续使用默认的 PHPMailer。

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!