README

这是一个 CakePHP 3 插件，允许您快速将电子邮件排队，以便在调用过程函数时发送。

默认支持 Mustache 模板和 Markdown。

为什么？

不能发送电子邮件确认就取消订单或延迟订单处理是不酷的。最好是将电子邮件排队，稍后批量处理。

安装

使用 Composer（如果你还不知道这是什么，去学习吧，它是个改变世界的工具）

composer require cwbit/cakephp-emailqueue:dev-master

加载插件

然后配置您的应用程序以实际加载此插件

	# in ../config/bootstrap.php
Plugin::load('EmailQueue', [
    'bootstrap' => true,        # let the plugin load its boostrap file
    'routes' => true,           # load the plugin routes file
    'ignoreMissing' => true,    # ignore missing routes or bootstrap file(s)
    'autoload' => true,      	# uncomment if you can't get composer to set the namespace/class location
    ]);

数据库安装

从您的应用程序目录内部运行以下迁移命令以为此插件构建数据库

 cd /path/to/your/app/root
 bin/cake migrations migrate --plugin EmailQueue

调整 Configure 设置

将 emailqueue.sample.php 复制到 emailqueue.php 并更改您需要的任何设置。这里您可以设置默认的邮件设置，如 sender 和 replyTo，甚至可以设置默认的 transport 层。

如果您需要将特定电子邮件发送给特定人员或通过特定的传输层，只需确保在数据库中的 EmailTemplate 记录中设置这些即可。

设置邮件模板

在您的数据库中设置一些 EmailTemplates，每个要发送的电子邮件类型一个。

此表中的列基于 Email::profile() 模式化，几乎任何 profile 接受的设置都可以在记录中设置。

您将为要发送的每种电子邮件类型创建一个这样的记录；例如，如果您有一个 password-reset 电子邮件，只需创建一个 EmailTemplate，其中 email_type = password-reset。

message_html 和 message_text 是 TEXT 字段，您可以在其中指定电子邮件的 html 和 text 消息的内容。

Configure::('EmailQueue.default.provider') 中的默认 provider(s) 允许使用 Mustache 模板和 Markdown 解析。如果您需要，可以创建自己的提供者并在 EmailTemplate 中设置它们。

插件使用

使用 EmailQueue 发送电子邮件是一个简单的两步过程

1. 设置模板
2. 排队电子邮件
3. 处理电子邮件队列（CRON）

设置模板

此插件版本的模板可以完全支持 Mustache 和 Markdown，并按此顺序（默认）处理 - 因此 Mustache 变量首先展开，然后整个内容通过 Markdown 解析为 HTML。

要设置模板，在数据库中添加一个 email_type 记录（例如 order-confirmation），设置一些基本元信息如 subject，并添加 message_text 和 message_html 块。

如果您查看 EmailQueue\config\Seeds\EmailTemplatesSeed.php，您可以看到一个 contact 电子邮件的示例。

view_vars 可以在排队电子邮件时传递，或在 EmailTemplate 中默认设置，也可以同时设置。它们以与控制器从视图文件传递视图变量相同的方式传递给电子邮件处理器，因此将以名称在 Mustache 的 {{varName}} 格式（如果您使用的是默认处理器）中可用。

好，让我们看看一个实际的电子邮件模板示例，比如 email_type = order-confirmation。

如果我们假设$order是一个实体，它包含我们在排队发送邮件时传递的订单详情（参见下一节），那么我们可以将view_vars设置为array('order'=>$order)，然后在我们的模板中设置message_html和/或message_text如下

# Order Confirmation

Hello, {{order.name}}

You ordered the following
{{#order.items}}
* Item Name: {{name}}; Price: {{price}}
{{/order.items}}

发送时，将会被解析为以下内容（使用默认处理器）

<h1>Order Confirmation</h1>

Hello, Arthur Dent

You ordered the following

<ul>
	<li>Item Name: Hitchhikers Guide; Price: $100000</li>
</ul>

排队发送邮件

将EmailQueue组件添加到您的控制器中

	# ../src/Controller/DemoController.php

	public function initialize()
	{
		parent::initialize();

		# load the EmailQueue's EmailQueueComponent
		$this->loadComponent('EmailQueue.EmailQueue');
	}

然后，要实际排队发送邮件，只需指定邮件的type、收件人to以及模板（在配置中设置EmailQueue.specific.{$type}）渲染自身时所需的任何viewVars。

	# in your controller function
	public function someRandomFunction()
	{
		# ... do some stuff ...

        $this->EmailQueue->quickAdd('demo', 'test@user.com', ['name'=>'Test User']);

	}

发送排队的邮件

手动运行，或添加到CRON，以下命令行命令

bin/cake EmailQueue.process

shell有以下选项

• --limit n或-l n
  • 将查询限制设置为n，其中n是一个整数。
  • 默认20
• --status foo或-s foo
  • 将只处理状态为foo的邮件
  • 选项：pending|failed|sent
  • 默认pending
• --type foo或-t foo
  • 将只处理类型为foo的邮件
  • 选项由Configure::read('EmailQueue.specific');构建
  • 默认all
• --id foo
  • 将只处理ID为foo的邮件（只要它也符合其他过滤器/配置设置）

所有选项都可以链在一起。

CLI 示例

要发送所有挂起的邮件，运行以下命令

bin/cake EmailQueue.process

要明确发送所有pending邮件，运行以下命令

bin/cake EmailQueue.process -s pending

要发送所有类型为order-confirmation的邮件，运行以下命令

bin/cake EmailQueue.process -t order-confirmation

要一次发送最多100封邮件，运行以下命令

bin/cake EmailQueue.process -l 100

要发送特定的邮件，运行以下命令

bin/cake EmailQueue.process --id "5869e7fd-ccf3-46c2-9b15-844335b9a86d"

要发送最多100封、failed、user-resetpw邮件，运行以下命令

bin/cake EmailQueue.process -l 100 -s failed -t user-resetpw