邮件

介绍

October提供SMTP，Mailgun，SparkPost，Amazon SES，PHP的mail功能和sendmail的驱动程序，使您可以快速开始通过您选择的本地或云服务发送邮件。 有两种方法可以配置邮件服务，可以通过设置>邮件设置使用后端界面，也可以通过更新默认配置值。 在这些示例中，我们将更新配置值。

驱动先决条件

在使用Mailgun，SparkPost或SES驱动程序之前，您需要安装Drivers plugin.。

Mailgun 驱动

要使用Mailgun驱动程序，请将config/mail.php配置文件中的driver选项设置为mailgun。 接下来，验证您的config/services.php配置文件包含以下选项：

  1. 'mailgun' => [
  2.     'domain' => 'your-mailgun-domain',
  3.     'secret' => 'your-mailgun-key',
  4. ],

SparkPost 驱动

要使用SparkPost驱动程序，请将config/mail.php配置文件中的driver选项设置为sparkpost。 接下来，验证您的config/services.php配置文件包含以下选项：

  1. 'sparkpost' => [
  2.     'secret' => 'your-sparkpost-key',
  3. ],

SES 驱动

要使用Amazon SES驱动程序，请将config/mail.php配置文件中的driver选项设置为ses。 然后，验证您的config/services.php配置文件包含以下选项：

  1. 'ses' => [
  2.     'key' => 'your-ses-key',
  3.     'secret' => 'your-ses-secret',
  4.     'region' => 'ses-region',  //e.g. us-east-1
  5. ],

发送邮件

要发送消息，请在Mailfacade上使用send方法，该方法接受三个参数。 第一个参数是一个唯一的邮件代码，用于定位邮件视图或邮件模板。 第二个参数是您希望传递给视图的数据数组。 第三个参数是一个Closure回调函数，它接收一个消息实例，允许您自定义邮件消息的收件人，主题和其他方面：

  1. //这些变量在消息中以Twig的形式提供
  2. $vars = ['name' => 'Joe', 'user' => 'Mary'];
  4. Mail::send('acme.blog::mail.message', $vars, function($message) {
  6.     $message->to('admin@domain.tld', 'Admin Person');
  7.     $message->subject('This is a reminder');
  9. });

由于我们在上面的示例中传递了一个包含name键的数组，因此我们可以使用以下Twig标记在电子邮件视图中显示该值：

  1. {{ name }}

注意: 你应该避免在你的消息中传递一个message变量，这个变量总是被传递并允许内联嵌入附件。

快速发送

October还包括一个名为sendTo的替代方法，可以简化发送邮件：

  1. //使用无名称发送到地址
  2. Mail::sendTo('admin@domain.tld', 'acme.blog::mail.message', $params);
  4. //使用对象的属性发送
  5. Mail::sendTo($user, 'acme.blog::mail.message', $params);
  7. //发送到多个地址
  8. Mail::sendTo(['admin@domain.tld' => 'Admin Person'], 'acme.blog::mail.message', $params);
  10. //或者，发送不带参数的原始消息
  11. Mail::rawTo('admin@domain.tld', 'Hello friend');

sendTo中的第一个参数用于收件人可以采用不同的值类型：

类型 描述
String 单个收件人地址，未定义名称。
Array 多个收件人，其中数组键是地址，值是名称。
Object 单个收件人对象，其中 email 属性用于地址，name 可选地用于名称。
Collection 如上所述的收件人对象的集合。

sendTo的完整签名如下：

  1. Mail::sendTo($recipient, $message, $params, $callback, $options);
  • $recipient 定义如上。
  • $message 是原始发送的模板名称或消息内容。
  • $params 模板内可用的变量数组。
  • $callback 使用一个参数调用，如send方法所述的消息构建器(可选，默认为null)。 如果不是可调用值，则作为下一个选项参数的替代。
  • $options 作为数组传递的自定义发送选项(可选)

支持以下自定义发送$options

  • queue 指定是对消息进行排队还是直接发送(可选，默认为false)。
  • bcc 指定将收件人添加为Bcc或常规To地址(默认为false)。

构建消息

如前所述，send方法的第三个参数是Closure，允许您在电子邮件本身上指定各种选项。 使用此结束，您可以指定消息的其他属性，例如抄送，盲抄送等：

  1. Mail::send('acme.blog::mail.welcome', $vars, function($message) {
  3.     $message->from('us@example.com', 'October');
  4.     $message->to('foo@example.com')->cc('bar@example.com');
  6. });

以下是$message消息构建器实例上可用方法的列表：

  1. $message->from($address, $name = null);
  2. $message->sender($address, $name = null);
  3. $message->to($address, $name = null);
  4. $message->cc($address, $name = null);
  5. $message->bcc($address, $name = null);
  6. $message->replyTo($address, $name = null);
  7. $message->subject($subject);
  8. $message->priority($level);
  9. $message->attach($pathToFile, array $options = []);
  11. //附加原始$data字符串中的文件...
  12. $message->attachData($data, $name, array $options = []);
  14. //Get the underlying SwiftMailer message instance...
  15. $message->getSwiftMessage();

注意: 传递给Mail::send Closure的消息实例扩展了SwiftMailer消息类，允许您调用该类的任何方法来构建您的电子邮件。

邮寄纯文本

默认情况下，假定给send方法的视图包含HTML。 但是，通过将数组作为第一个参数传递给send方法，除了HTML视图之外，您还可以指定要发送的纯文本视图：

  1. Mail::send(['acme.blog::mail.html', 'acme.blog::mail.text'], $data, $callback);

或者，如果您只需要发送纯文本电子邮件，则可以使用数组中的text键指定：

  1. Mail::send(['text' => 'acme.blog::mail.text'], $data, $callback);

邮寄解析的原始字符串

如果您希望直接通过电子邮件发送原始字符串，可以使用raw方法。 此内容将由Markdown解析。

  1. Mail::raw('Text to e-mail', function ($message) {
  2.     //
  3. });

此外，这个字符串将由Twig解析，如果您希望将变量传递给此环境，请使用send方法，将内容作为raw键传递。

  1. Mail::send(['raw' => 'Text to email'], $vars, function ($message) {
  2.     //
  3. });

邮寄原始字符串

如果传递包含text或html键的数组，这将是发送邮件的显式请求。 不使用布局或markdown解析。

  1. Mail::raw([
  2.     'text' => 'This is plain text',
  3.     'html' => '<strong>This is HTML</strong>'
  4. ], function ($message) {
  5.     //
  6. });

附件

要向电子邮件添加附件，请在传递给Closure的$message对象上使用attach方法。 attach方法接受文件的完整路径作为其第一个参数：

  1. Mail::send('acme.blog::mail.welcome', $data, function ($message) {
  2.     //
  4.     $message->attach($pathToFile);
  5. });

将文件附加到消息时，您还可以通过将array作为第二个参数传递给attach方法来指定显示名称和/或MIME类型：

  1. $message->attach($pathToFile, ['as' => $display, 'mime' => $mime]);

内联附件

在邮件内容中嵌入图像

将内嵌图像嵌入电子邮件通常很麻烦; 但是，有一种方便的方法可以将图像附加到您的电子邮件中并检索相应的CID。 要嵌入内嵌图像，请在电子邮件视图中的message变量上使用embed方法。 请记住，message变量可用于所有邮件视图：

  1. <body>
  2.     Here is an image:
  4.     <img src="/uploads/projects/octobercms-docs-zh//uploads/projects/octobercms-docs-zh/{{ message.embed(pathToFile) }}">
  5. </body>

如果您计划使用排队的电子邮件，请确保该文件的路径是绝对的。 要实现这一点，您只需使用app filter：

  1. <body>
  2.     Here is an image:
  3.     {% set pathToFile = 'storage/app/media/path/to/file.jpg' | app %}
  4.     <img src="/uploads/projects/octobercms-docs-zh//uploads/projects/octobercms-docs-zh/{{ message.embed(pathToFile) }}">
  5. </body>

在邮件内容中嵌入原始数据

如果您已经有一个希望嵌入电子邮件消息的原始数据字符串，则可以在message变量上使用embedData方法：

  1. <body>
  2.     Here is an image from raw data:
  4.     <img src="/uploads/projects/octobercms-docs-zh/{{ message.embedData(data, name) }}">
  5. </body>

排队邮件

邮件使用队列

由于发送邮件消息可以大大延长应用程序的响应时间，因此许多开发人员选择将消息排队以进行后台发送。 使用内置的统一队列API很容易。 要对邮件消息进行排队，请在Mailfacade上使用queue方法：

  1. Mail::queue('acme.blog::mail.welcome', $data, function ($message) {
  2.     //
  3. });

此方法将自动将作业推送到队列以在后台发送邮件消息。 当然，在使用此功能之前，您需要配置队列。

延迟消息排队

如果您希望延迟传送排队的电子邮件，可以使用later方法。 要开始，只需将您希望延迟发送消息的秒数作为方法的第一个参数传递：

  1. Mail::later(5, 'acme.blog::mail.welcome', $data, function ($message) {
  2.     //
  3. });

推送到特定队列

如果您希望指定一个特定的队列来推送消息，您可以使用queueOn和laterOn方法：

  1. Mail::queueOn('queue-name', 'acme.blog::mail.welcome', $data, function ($message) {
  2.     //
  3. });
  5. Mail::laterOn('queue-name', 5, 'acme.blog::mail.welcome', $data, function ($message) {
  6.     //
  7. });

消息内容

可以使用邮件视图或邮件模板在October发送邮件。 邮件视图由 /views 目录中文件系统中的应用程序或插件提供。 而使用后端界面通过 系统>邮件模版 管理邮件模板。 所有邮件消息都支持使用Twig进行标记。

可选地，邮件视图可以[使用registerMailTemplates方法在插件注册文件中注册。 这将自动生成邮件模板，并允许使用后端界面对其进行自定义。

邮件视图

邮件视图驻留在文件系统中，使用的代码表示视图文件的路径。 例如，使用代码 author.plugin::mail.message发送邮件将使用以下文件中的内容：

  1. plugins/                <=== Plugins directory
  2.   author/               <=== "author" segment
  3.     plugin/             <=== "plugin" segment
  4.       views/            <=== View directory
  5.         mail/           <=== "mail" segment
  6.           message.htm    <=== "message" segment

邮件视图文件中的内容最多可包含3个部分：配置，纯文本和 HTML标记。 截面用==序列分隔。 例如：

  1. subject = "Your product has been added to OctoberCMS project"
  2. ==
  4. Hi {{ name }},
  6. Good news! User {{ user }} just added your product "{{ product }}" to a project.
  8. This message was sent using no formatting (plain text)
  9. ==
  11. <p>Hi {{ name }},</p>
  13. <p>Good news! User {{ user }} just added your product <strong>{{ product }}</strong> to a project.</p>
  15. <p>This email was sent using formatting (HTML)</p>

注意: 邮件视图中支持基本的Twig标记和表达式。

纯文本部分是可选的，视图只能包含配置和HTML标记部分。

  1. subject = "Your product has been added to OctoberCMS project"
  2. ==
  4. <p>Hi {{ name }},</p>
  6. <p>This email does not support plain text.</p>
  8. <p>Sorry about that!</p>

配置部分

配置部分设置邮件视图参数。 支持以下配置参数：

参数 描述
subject 邮件主题，必填。
layout 邮件布局代码，可选。 默认值为default。

使用邮件模板

邮件模板驻留在数据库中，可以通过 设置>邮件>邮件模板 在后端区域中创建。 模板中指定的代码是唯一标识符，一旦创建就无法更改。

发送这些电子邮件的过程是相同的。 例如，如果您使用代码 this.is.my.email 创建模板，则可以使用以下PHP代码发送它：

  1. Mail::send('this.is.my.email', $data, function($message) use ($user)
  2. {
  3.     [...]
  4. });

注意: 如果系统中不存在邮件模板，则此代码将尝试查找具有相同代码的邮件视图。

自动生成的模板

邮件模板也可以通过已注册的邮件视图自动生成。 code值与邮件视图路径相同(例如：author.plugin：mail.message)。 如果邮件视图定义了 layout 参数，则将使用此参数为模板提供布局。

首次保存生成的模板时，将在为指定的代码发送邮件时使用自定义内容。 在此上下文中，邮件视图可以被视为默认视图。

使用邮件布局

通过选择 设置>邮件>邮件模板 并单击 布局 选项卡，可以创建邮件布局。 这些行为就像CMS布局一样，它们包含邮件消息的脚手架。 邮件视图和模板支持使用邮件布局。

默认情况下，十月带有两个主要邮件布局：

布局 Code 描述
Default default Used for public facing, front-end mail
System system Used for internal, back-end mail

注册邮件模板

邮件视图可以注册为在后端自动生成的模板，以便进行自定义。 可以通过设置>邮件模板菜单自定义邮件模板。 可以通过覆盖插件注册类的registerMailTemplates方法来注册模板。

  1. public function registerMailTemplates()
  2. {
  3.     return [
  4.         'rainlab.user::mail.activate' => 'Activation mail sent to new users.',
  5.         'rainlab.user::mail.restore'  => 'Password reset instructions for front-end users.'
  6.     ];
  7. }

该方法应返回一个数组，其中键是邮件视图名称，该值提供有关邮件模板用途的简要说明。

全局变量

您可以使用View::share方法注册所有邮件模板全局可用的变量。

  1. View::share('site_name', 'OctoberCMS');

可以在插件注册文件的寄存器或引导方法内调用此代码。 使用上面的示例，变量{{site_name}}将在所有邮件模板中可用。

邮件和本地开发

在开发发送电子邮件的应用程序时，您可能不希望实际发送电子邮件到实时电子邮件地址。 有几种方法可以“禁用”实际发送的电子邮件。

日志驱动

一种解决方案是在本地开发期间使用log邮件驱动程序。 此驱动程序会将所有电子邮件写入您的日志文件以供检查。 有关按环境配置应用程序的更多信息，请查看配置文档。

Universal to

另一种解决方案是设置框架发送的所有电子邮件的通用接收者。 这样，应用程序生成的所有电子邮件都将发送到特定地址，而不是发送邮件时实际指定的地址。 这可以通过config/mail.php配置文件中的to选项来完成：

  1. 'to' => [
  2.     'address' => 'dev@example.com',
  3.     'name' => 'Dev Example'
  4. ],

假装邮件模式

您可以使用Mail::pretend方法动态禁用发送邮件。 当邮件程序处于伪装模式时，邮件将写入应用程序的日志文件，而不是发送给收件人。

  1. Mail::pretend();