README

Yii2 的 Mandrill API 集成

安装

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

运行以下命令之一

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

或在您的 composer.json 文件的 require 部分添加以下内容

"nickcv/yii2-mandrill": "*"

。

设置

要使用 Mandrill，您需要一个 Mandrill 账户。

每个账户每月可以免费发送高达 12k 封电子邮件。

超出此阈值的电子邮件发送费用非常低 。

一旦您有了账户，您需要创建一个 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 模板时，组件不会默认使用应用程序名称和 admin 电子邮件。这样做是为了允许使用 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 对象。

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

单元测试

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

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

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

日志

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

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

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