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密钥提交的每封电子邮件实际上都不会提交，但您可以在测试仪表板中检查测试是否成功。

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 方法中 view 参数命名的名称存在于 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 通过 Mandril 模板发送多个电子邮件

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

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

单元测试

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

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

测试使用开发人员 Mandrill 测试 API 密钥，该密钥仅对开发人员 IP 白名单。

日志

组件会自动将每个通过 mandrill 发送的消息记录在 "mandrill" 类别中。

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

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