README

Drupal 8 中发送邮件的现代、基于插件的 API。灵感来自 Laravel

为什么？

• 在 Drupal 8 中没有处理邮件的现代方法：使用 hook_mail 和 hook_theme 与 wmmodel、wmcontroller 等不符合 Wieni Drupal 流程。
• 没有干净的面向对象 API，例如要添加 CC / BCC 地址，必须手动添加标题
• 不够直观，逻辑分散在多个文件中，容易变得混乱

安装

此软件包需要 PHP 7.1 和 Drupal 8 或更高版本。可以使用 Composer 进行安装。

 composer require wieni/wmmailable

它如何工作？

构建邮件

• 邮件是注释插件
• 每个类代表一个邮件
• 通过实现 ContainerFactoryPluginInterface 可以进行依赖注入 (教程)

<?php

namespace Drupal\wmcustom\Mail;

/**
 * @Mailable(
 *     id = "contact_form_submission",
*      template = "mail.contact-submission"
 * )
 */
class ContactFormSubmission extends MailableBase
{
    public function build(array $parameters): MailableInterface;
}

• 发送邮件时可以接管其他模块的邮件。为此，更改 id 和 module 属性。原始邮件参数将传递给 build 方法。示例

<?php

namespace Drupal\wmcustom\Mail;

/**
 * @Mailable(
 *     id = "register_no_approval_required",
 *     module = "user",
 *     template = "mail.account-confirmation"
 * )
 */
class AccountConfirmationMail extends MailableBase
{
    public function build(array $parameters): MailableInterface
    {
        $parameters['oneTimeLoginUrl'] = user_pass_reset_url($parameters['account']);
        
        {...}
    }
}

主题邮件

• 邮件模板应存储在主题中。此主题可以在 wmmailable.settings 配置的 theme 值中设置，默认主题作为后备。

• 模板在主题中的位置也可以配置

  • 默认位置在 mail 子文件夹中，模板名称使用短横线代替下划线。
  • 可以在注释中设置自定义位置，形式为相对于主题的路径，带有文件名但没有扩展名。点可以用作目录分隔符。

• 邮件格式化器决定邮件的渲染方式。由于有 mailsystem 模块，我们可以单独更改邮件格式化器，而不仅仅是邮件发送者。此模块提供 3 个格式化器。以下列出的格式化器是增量：它们都包含前一个格式化器中列出的功能。

  • Mailable - Plain：最基础的邮件格式化器。根据传递的 Content-Type 标题，此格式化器将输出 HTML 或纯文本邮件。
  • Mailable - With inline styles：允许通过传递到 MailableInterface::addLibrary 或数组形式的资产库到 MailableInterface::setLibraries 来将 asset libraries 添加到邮件中。
  • Mailable - Foundation for Emails：允许使用 Inky 模板语言编写邮件。要使用此格式化器，需要安装 thampe/inky 软件包。

发送邮件

• 邮件通过 Mailer 服务发送
• 提供了两个标准 Mailer 实现：mailable.mailer.direct 和 mailable.mailer.queued
• 可以在 mailable.settings.yml 配置中更改活动实现

<?php

namespace Drupal\wmcustom\Form;

use Drupal\wmmailable\Mailer\MailerInterface;

class ContactForm extends FormBase
{
    /** @var MailerInterface */
    protected $mailer;

    public function __construct(
        MailerInterface $mailer
    ) {
        $this->mailer = $mailer;
    }

    public function submitForm(array &$form, FormStateInterface $formState)
    {
        $mail = $this->mailer->create('contact_form_submission')
            ->setRecepients(['Wieni <info@wieni.be>', 'dieter@wieni.be'])
            ->addBcc('sophie@wieni.be')
            ->setParameters(
                compact('domain', 'firstName', 'lastName', 'email', 'question')
            );
        
        $this->mailer->send($mail);
	}

	public static function create(ContainerInterface $container)
	{
	    return new static(
	        $container->get('mailable.mailer')
        );
    }
}

记录发送的邮件

• 启用后，这将记录所有发出的邮件，包括那些不是通过此模块编写的。
• 要启用，配置 mailsystem 模块使用 邮件 - 记录器 作为邮件发送者。
• 要查看已记录的邮件，请访问 /admin/reports/sent-mails 或在 报告 > 已发送邮件 的菜单链接。

钩子和事件

• 提供了两个钩子，hook_mailable_alter 和 hook_mailable_{module}_{key}_alter。这些钩子在调用 mailable 的 send 方法后、邮件发送前被调用。

<?php

function wmcustom_mailable_alter(MailableInterface $mail)
{
    $mail->setHeader('X-SES-SOURCE-ARN', '<...>');
}

• 提供了两个事件，与钩子等效

<?php

use Drupal\wmmailable\Event\MailableAlterEvent;
use Drupal\wmmailable\WmmailableEvents;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class MailableAlterSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        $events[WmmailableEvents::MAILABLE_ALTER][] = 'onMailAlter';

        return $events;
    }

    public function onMailAlter(MailableAlterEvent $event)
    {
        $mailable = $event->getMailable();
        $mailable->setSubject("Here's a better subject.");
    }
}

更新日志

此项目的所有重大更改都将记录在 更新日志 文件中。

安全

如果您发现任何与安全相关的问题，请发送电子邮件至 security@wieni.be 而不是使用问题跟踪器。

许可协议

在 MIT 许可协议下分发。有关更多信息，请参阅 许可协议 文件。