Mail

• Introduction
• 发送邮件
  • Attachments
  • 内联附件
  • 排队邮件
• 留言内容
  • 邮件浏览量
  • 邮件模板
  • 邮件布局
  • 注册邮件布局、模板和部分
  • 全局变量
• 邮件和本地开发

#Introduction

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

#驱动程序先决条件

在使用 Mailgun、SparkPost 或 SES 驱动程序之前，您需要安装驱动插件.

邮枪司机

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

'mailgun' => [
    'domain' => 'your-mailgun-domain',
    'secret' => 'your-mailgun-key',
    'endpoint' => 'api.mailgun.net', // api.eu.mailgun.net for EU
],

SparkPost驱动程序

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

'sparkpost' => [
    'secret' => 'your-sparkpost-key',
],

SES驱动程序

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

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

#发送邮件

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

// These variables are available inside the message as Twig
$vars = ['name' => 'Joe', 'user' => 'Mary'];

Mail::send('acme.blog::mail.message', $vars, function($message) {

    $message->to('admin@domain.tld', 'Admin Person');
    $message->subject('This is a reminder');

});

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

{{ name }}

NOTE: 你应该避免传递一个message 消息中的变量，此变量始终被传递并允许内嵌附件.

快速发送

Winter 还包括一种替代方法，称为sendTo 可以简化发送邮件：

// Send to address using no name
Mail::sendTo('admin@domain.tld', 'acme.blog::mail.message', $params);

// Send using an object's properties
Mail::sendTo($user, 'acme.blog::mail.message', $params);

// Send to multiple addresses
Mail::sendTo(['admin@domain.tld' => 'Admin Person'], 'acme.blog::mail.message', $params);

// Alternatively send a raw message without parameters
Mail::rawTo('admin@domain.tld', 'Hello friend');

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

的完整签名sendTo 如下：

Mail::sendTo($recipient, $message, $params, $callback, $options);

• $recipient 定义如上。
• $message 是原始发送的模板名称或消息内容。
• $params 模板中可用的变量数组。
• $callback 被调用时带有一个参数，即消息生成器，如send 方法（可选，默认为空）。如果不是可调用值，则作为下一个选项参数的替代品。
• $options 作为数组传递的自定义发送选项（可选）

以下自定义发送$options 支持

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

构建消息

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

Mail::send('acme.blog::mail.welcome', $vars, function($message) {

    $message->from('us@example.com', 'Winter');
    $message->to('foo@example.com')->cc('bar@example.com');

});

这是可用方法的列表$message 消息生成器实例：

$message->from($address, $name = null);
$message->sender($address, $name = null);
$message->to($address, $name = null);
$message->cc($address, $name = null);
$message->bcc($address, $name = null);
$message->replyTo($address, $name = null);
$message->subject($subject);
$message->priority($level);
$message->attach($pathToFile, array $options = []);

// Attach a file from a raw $data string...
$message->attachData($data, $name, array $options = []);

// Get the underlying SwiftMailer message instance...
$message->getSwiftMessage();

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

邮寄纯文本

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

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

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

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

邮寄已解析的原始字符串

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

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

此外，这个字符串将由 Twig 解析，如果你想将变量传递给这个环境，请使用send 方法，而是将内容作为raw 钥匙。

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

邮寄原始字符串

如果您传递一个数组，其中包含text 或者html 密钥，这将是发送邮件的明确请求。不使用布局或降价解析。

Mail::raw([
    'text' => 'This is plain text',
    'html' => '<strong>This is HTML</strong>'
], function ($message) {
    //
});

这也适用于使用Mail::rawTo()

Mail::rawTo('name@example.com', [
    'text' => 'This is plain text',
    'html' => '<strong>This is HTML</strong>'
]);

#Attachments

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

Mail::send('acme.blog::mail.welcome', $data, function ($message) {
    //

    $message->attach($pathToFile);
});

将文件附加到邮件时，您还可以通过传递array 作为第二个参数attach 方法：

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

#内联附件

在邮件内容中嵌入图像

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

<body>
    Here is an image:

    <img src="{{ message.embed(pathToFile) }}">
</body>

如果您打算使用排队的电子邮件，请确保文件的路径是绝对路径。为此，您可以简单地使用应用过滤器:

<body>
    Here is an image:
    {% set pathToFile = 'storage/app/media/path/to/file.jpg' | app %}
    <img src="{{ message.embed(pathToFile) }}">
</body>

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

如果您已经有了想要嵌入到电子邮件中的原始数据字符串，您可以使用embedData 上的方法message 多变的：

<body>
    Here is an image from raw data:

    <img src="{{ message.embedData(data, name) }}">
</body>

#排队邮件

排队邮件消息

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

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

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

延迟消息队列

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

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

推送到特定队列

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

Mail::queueOn('queue-name', 'acme.blog::mail.welcome', $data, function ($message) {
    //
});

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

#留言内容

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

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

#邮件浏览量

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

📂 plugins                 <=== Plugins directory
┗ 📂 author                <=== "author" segment
  ┗ 📂 plugin              <=== "plugin" segment
    ┗ 📂 views             <=== View directory
      ┗ 📂 mail            <=== "mail" segment
        ┗ 📜 message.htm   <=== "message" segment

邮件视图文件中的内容最多可包含 3 个部分：configuration,纯文本， 和HTML 标记.部分用== 顺序。例如：

subject = "Your product has been added to Winter CMS project"
==

Hi {{ name }},

Good news! User {{ user }} just added your product "{{ product }}" to a project.

This message was sent using no formatting (plain text)
==

<p>Hi {{ name }},</p>

<p>Good news! User {{ user }} just added your product <strong>{{ product }}</strong> to a project.</p>

<p>This email was sent using formatting (HTML)</p>

NOTE: 邮件视图支持基本的 Twig 标签和表达式。

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

subject = "Your product has been added to Winter CMS project"
==

<p>Hi {{ name }},</p>

<p>This email does not support plain text.</p>

<p>Sorry about that!</p>

配置部分

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

#使用邮件模板

邮件模板驻留在数据库中，可以通过以下方式在后端区域创建设置 > 邮件 > 邮件模板.这code 模板中指定的是唯一标识符，一旦创建就不能更改。

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

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

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

自动生成的模板

邮件模板也可以自动生成已注册的邮件视图.这code 值将与邮件视图路径相同（例如：author.plugin:mail.message）。如果邮件视图有layout 参数已定义，这将用于为模板提供布局。

第一次保存生成的模板时，发送指定代码的邮件时将使用自定义内容。在这种情况下，邮件视图可以被认为是默认视图.

#使用邮件布局

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

默认情况下，Winter 带有两种主要的邮件布局：

#注册邮件布局、模板和部分

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

public function registerMailTemplates()
{
    return [
        'winter.user::mail.activate',
        'winter.user::mail.restore'
    ];
}

该方法应返回一个数组邮件视图名称.

像模板一样，邮件部分和布局可以通过覆盖registerMailPartials 和registerMailLayouts 的方法插件注册类.

public function registerMailPartials()
{
    return [
        'tracking'  => 'acme.blog::partials.tracking',
        'promotion' => 'acme.blog::partials.promotion',
    ];
}

public function registerMailLayouts()
{
    return [
        'marketing'    => 'acme.blog::layouts.marketing',
        'notification' => 'acme.blog::layouts.notification',
    ];
}

这些方法应该返回一个数组邮件视图名称.数组键将用作code 部分或布局的属性。

#全局变量

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

View::share('site_name', 'Winter CMS');

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

#邮件和本地开发

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

日志驱动

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

通用到

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

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

假装邮件模式

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

Mail::pretend();