README

为 Yii2 的 Mandrill Api 集成

变更日志

从 版本 1.6.1 开始，方法 nickcv\mandrill\Message::setHtmlBody 和 nickcv\mandrill\Message::setSubject 不会自动净化/编码数据。

这是为了给开发者提供更大的灵活性，请参阅问题 #16 和 #19。

安装

安装此扩展的首选方式是通过 composer。

运行以下命令之一

php composer.phar require --prefer-dist nickcv/yii2-mandrill "*"

或

"nickcv/yii2-mandrill": "*"

将其添加到您的 composer.json 文件的 require 部分。

设置

最近 Mandrill 成为 MailChilmp 服务：要使用 Mandrill，您需要一个 MailChimp 账户。

有关定价的详细信息，请参阅 他们的网站。

一旦您有了账户，您需要创建一个 API 密钥。您可以创建任意数量的 API 密钥，并且为每个网站创建一个 API 密钥是最佳实践。您还可以创建 测试 API 密钥。使用测试 API 密钥提交的每封电子邮件实际上都不会提交，但您可以在 测试仪表板 中检查测试是否成功。

Mandrill 会跟踪您提交的每一封电子邮件。您可以使用标签来筛选数据，并且您还可以检查每封电子邮件被打开的次数以及其中的链接是否被点击。

使用

安装扩展后，更改您的应用程序配置文件 web.php

首先，您需要添加一个 应用程序名称。默认情况下，此扩展将使用应用程序名称作为发件人名称，并使用 params.php 中的 adminEmail 参数作为发件人电子邮件。

[
	'id' => 'basic',
	'name' => 'Application Name',
]

return [
    'adminEmail' => 'admin@example.com',
];

然后，您需要添加以下组件

    'mailer' => [
        'class' => 'nickcv\mandrill\Mailer',
        'apikey' => 'YourApiKey',
    ],

从现在起，您可以使用 Mandrill 邮件发送器，就像以前使用默认发送器一样。

\Yii::$app->mailer
    ->compose('mailViewName', ['model' => $model])
    ->setTo('email@email.com')
    ->send();

Mandrill 模板

如果您想使用 Mandrill 的模板系统，只需在组件配置中将 useMandrillTemplates 属性设置为 true

    'mailer' => [
        'class' => 'nickcv\mandrill\Mailer',
        'apikey' => 'YourApiKey',
        'useMandrillTemplates' => true,
    ],

如果您启用此功能，组件将查找名为 compose 方法视图参数的 Mandrill 中的模板。

自1.3.0版本起，组件将停止回退到渲染内部视图。这次更改是因为现在将使用Mandrill的send-template方法，避免了在模板启用时进行两次API调用。

自1.4.0版本起，当使用Mandrill模板时，组件不会默认使用应用程序名称和管理员邮箱。这样做是为了允许使用Mandrill的默认模板值。

要覆盖此行为，您可以在组件配置中将useTemplateDefaults属性设置为false。

    'mailer' => [
        'class' => 'nickcv\mandrill\Mailer',
        'apikey' => 'YourApiKey',
        'useMandrillTemplates' => true,
        'useTemplateDefaults' => false,
    ],

自1.5.0版本起，组件具有一个可配置属性templateLanguage，可以包含'mailchimp'或'handlebars'（默认为'mailchimp'）。

有关handlebars使用的更多信息，请查看以下链接

• Mandrill文档
• Handlebars文档

您可以通过编辑组件配置中的templateLanguage属性来更改首选语言

    'mailer' => [
        'class' => 'nickcv\mandrill\Mailer',
        'apikey' => 'YourApiKey',
        'useMandrillTemplates' => true,
        'templateLanguage' => nickcv\mandrill\Mailer::LANGUAGE_HANDLEBARS,
    ],

附加方法

Mandrill允许您设置标签。方法\nickcv\mandrill\Message::setTags($tags)接受一个字符串或字符串数组作为参数

\Yii::$app->mailer
    ->compose('mailViewName', ['model' => $model])
    ->setTags(['registration']);

自1.3.0版本起，还可能启用异步模式。当使用异步模式时，Mandrill将队列消息并批量发送。如果您向超过10个电子邮件地址发送消息，将自动使用异步模式。

\Yii::$app->mailer
    ->compose('mailViewName', ['model' => $model])
    ->enableAsync();

自1.4.0版本起，还可能使用全局合并变量。这些变量将由Mandrill用于替换占位符。这在处理模板时非常有用。

自1.6.0版本起，您可以通过调用Mailer::getMandrill方法来获取组件使用的Mandrill对象。

有关更多信息，请查看组件文档。

自1.7.0版本起，还可能启用/禁用消息点击/打开跟踪，并决定它是否为优先消息。

您还可以使用Mailer::getLastTransaction方法检索Mandrill返回的完整响应体。

使用merge_vars通过Mandrill模板发送多封邮件

您可以考虑使用此方法来使用Mandrill模板并根据您的数据更改变量

\Yii::$app->mailer
    ->compose($stringTemplate)
    ->setTo($arrayTo)
    ->setGlobalMergeVars($arrayGolbalMergeVars)
    ->setMergeVars($arrayMergeVars)
    ->send();

单元测试

包内的所有类都已进行单元测试。测试包含在包中。

如果您想运行测试，请根据Yii2文档安装phpunit。

测试使用开发者的Mandrill测试API密钥，该密钥仅对开发者IP进行白名单。

日志

组件会自动在“mandrill”类别中记录通过Mandrill发送的每条消息。

成功发送的消息使用\Yii::info()记录，拒绝或无效的消息使用\Yii::warning()记录，Mandrill类抛出的所有异常使用\Yii::error()记录。

如果您使用Mandrill模板且模板未找到，错误将使用Yii::info()记录。