Extending the functionality of the Drupal 8 Mail API: Part 1

In this two-part series, we’ll explore the Mail API in Drupal 8. Along the way, we'll cover two main aspects: how to use it programmatically to send emails and how to extend it to use external services like Mandrill.

To demonstrate this, in the first part, we will create a custom email template that sends an email to the current user when he/she saves a new article node. Additionally, we'll look at how others have changed this template to allow HTML to render the email body instead of the default plain text.

In the second part, we will look at extending the mail system and integrating external APIs for email delivery. For this we will use Mandrill and its PHP library, which provides a good basis for interacting with its API.

All the work we've done can be found in this Git repository as part of the custom Drupal 8 module we'll start writing here. So if you want to follow along, feel free to check it out. let's start.

The first prerequisite for this module is its .info file:

d8mail.info.yml：

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

With this issue resolved, we can enable the module on our site if desired.

How do we send emails?

Sending emails programmatically using Drupal 8 requires two main steps. We first need to implement hook_mail() to define one or more email templates. The second step is to use your mail manager to send an email using one of these templates.

Although called a hook, hook_mail() is not a typical hook, but more of a regular function, usually only called by the same module that implements it. In other words, when you send an email programmatically, you need to specify the name of the module that implements hook_mail() and the template id that you want to use and that is defined by that hook. But we'll see that soon. First, how do we implement it?

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;
  }
}

This is a very simple implementation that defines a template identified as node_insert ($key). The other two function parameters are:

• $message: Pass by reference, where we add as much boilerplate about the email as needed
• $params: Array of extra data that needs to be put into the email, passed from the mail manager when we try to send the email

As you can see, we are building a $message array that contains the values ​​we want this email to include in all calls. We are setting a default from value that is retrieved from the configuration system and represents the main site email address. We set up a boilerplate email subject that lets the recipient know that a new node has been created, followed by the name of the node (which will be passed in via the $params array). The topic can also be translated into the language passed from the caller.

Finally, we run the message body through a string sanitizer because the text may contain HTML and it may be truncated if we don't encode the HTML element. Since we are using the SafeMarkup class, we need to use it at the top:

use Drupal\Component\Utility\SafeMarkup;

Additionally, the message body is an array, which will later implode into a string. Obviously there are many other parameters we can set, such as headers, but this is enough for this example.

This is all the implementation of hook_mail(). Now let's look at the code that runs every time a new node is created, 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);
}

This hook will be triggered after every node save, all we have to do is make sure we target the correct node and include our logic.

After checking that the node entity is of type article, we load the Drupal Mail Manager service and start setting some values ​​for the email. We need the following information:

• 实现 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。

The above is the detailed content of Extending the functionality of the Drupal 8 Mail API: Part 1. For more information, please follow other related articles on the PHP Chinese website!