Laravel 5.5 中文文档

简体中文

English

简体中文

English

主题

邮件 ​

介绍 ​

Laravel 提供了一个简洁、简单的 API，基于流行的 SwiftMailer 库，支持 SMTP、Mailgun、SparkPost、Amazon SES、PHP 的 mail 函数和 sendmail 驱动程序，允许您快速开始通过本地或云服务发送邮件。

驱动程序先决条件 ​

基于 API 的驱动程序如 Mailgun 和 SparkPost 通常比 SMTP 服务器更简单、更快。如果可能，您应该使用这些驱动程序。所有 API 驱动程序都需要 Guzzle HTTP 库，可以通过 Composer 包管理器安装：

php
composer require guzzlehttp/guzzle

Mailgun 驱动程序 ​

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

php
'mailgun' => [
    'domain' => 'your-mailgun-domain',
    'secret' => 'your-mailgun-key',
],

SparkPost 驱动程序 ​

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

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

SES 驱动程序 ​

要使用 Amazon SES 驱动程序，您必须首先安装 Amazon AWS SDK for PHP。您可以通过在 composer.json 文件的 require 部分添加以下行并运行 composer update 命令来安装此库：

php
"aws/aws-sdk-php": "~3.0"

接下来，在 config/mail.php 配置文件中将 driver 选项设置为 ses，并验证您的 config/services.php 配置文件包含以下选项：

php
'ses' => [
    'key' => 'your-ses-key',
    'secret' => 'your-ses-secret',
    'region' => 'ses-region',  // 例如 us-east-1
],

生成可邮寄的类 ​

在 Laravel 中，应用程序发送的每种类型的电子邮件都表示为一个“可邮寄的”类。这些类存储在 app/Mail 目录中。如果您在应用程序中没有看到此目录，不用担心，因为当您使用 make:mail 命令创建第一个可邮寄的类时，它将为您生成：

php
php artisan make:mail OrderShipped

编写可邮寄的类 ​

所有可邮寄类的配置都在 build 方法中完成。在此方法中，您可以调用各种方法，如 from、subject、view 和 attach，以配置电子邮件的展示和传递。

配置发件人 ​

使用 from 方法 ​

首先，让我们探讨如何配置电子邮件的发件人。换句话说，电子邮件将从谁那里发送。有两种方法可以配置发件人。首先，您可以在可邮寄类的 build 方法中使用 from 方法：

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    return $this->from('example@example.com')
                ->view('emails.orders.shipped');
}

使用全局 from 地址 ​

然而，如果您的应用程序为所有电子邮件使用相同的“发件人”地址，那么在每个生成的可邮寄类中调用 from 方法可能会变得繁琐。相反，您可以在 config/mail.php 配置文件中指定一个全局“发件人”地址。如果在可邮寄类中没有指定其他“发件人”地址，将使用此地址：

php
'from' => ['address' => 'example@example.com', 'name' => 'App Name'],

配置视图 ​

在可邮寄类的 build 方法中，您可以使用 view 方法指定在渲染电子邮件内容时应使用哪个模板。由于每封电子邮件通常使用 Blade 模板 来渲染其内容，因此在构建电子邮件的 HTML 时，您可以充分利用 Blade 模板引擎的强大功能和便利性：

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped');
}
lightbulb

您可能希望创建一个 resources/views/emails 目录来存放所有电子邮件模板；然而，您可以自由地将它们放置在 resources/views 目录中的任何位置。

纯文本电子邮件 ​

如果您想定义电子邮件的纯文本版本，可以使用 text 方法。与 view 方法一样，text 方法接受一个模板名称，该模板将用于渲染电子邮件的内容。您可以自由地定义消息的 HTML 和纯文本版本：

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->text('emails.orders.shipped_plain');
}

视图数据 ​

通过公共属性 ​

通常，您会希望将一些数据传递给视图，以便在渲染电子邮件的 HTML 时使用。有两种方法可以使数据在视图中可用。首先，定义在可邮寄类上的任何公共属性将自动在视图中可用。因此，例如，您可以将数据传递到可邮寄类的构造函数中，并将该数据设置为类上定义的公共属性：

php
<?php

namespace App\Mail;

use App\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * 订单实例。
     *
     * @var Order
     */
    public $order;

    /**
     * 创建一个新的消息实例。
     *
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }

    /**
     * 构建消息。
     *
     * @return $this
     */
    public function build()
    {
        return $this->view('emails.orders.shipped');
    }
}

一旦数据被设置为公共属性，它将自动在视图中可用，因此您可以像访问 Blade 模板中的任何其他数据一样访问它：

php
<div>
    价格: {{ $order->price }}
</div>

通过 with 方法 ​

如果您希望在将数据发送到模板之前自定义其格式，可以通过 with 方法手动将数据传递给视图。通常，您仍然会通过可邮寄类的构造函数传递数据；然而，您应该将此数据设置为 protected 或 private 属性，以便数据不会自动在模板中可用。然后，在调用 with 方法时，传递一个您希望在模板中可用的数据数组：

php
<?php

namespace App\Mail;

use App\Order;
use Illuminate\Bus\Queueable;
use Illuminate\Mail\Mailable;
use Illuminate\Queue\SerializesModels;

class OrderShipped extends Mailable
{
    use Queueable, SerializesModels;

    /**
     * 订单实例。
     *
     * @var Order
     */
    protected $order;

    /**
     * 创建一个新的消息实例。
     *
     * @return void
     */
    public function __construct(Order $order)
    {
        $this->order = $order;
    }

    /**
     * 构建消息。
     *
     * @return $this
     */
    public function build()
    {
        return $this->view('emails.orders.shipped')
                    ->with([
                        'orderName' => $this->order->name,
                        'orderPrice' => $this->order->price,
                    ]);
    }
}

一旦数据被传递给 with 方法，它将自动在视图中可用，因此您可以像访问 Blade 模板中的任何其他数据一样访问它：

php
<div>
    价格: {{ $orderPrice }}
</div>

附件 ​

要向电子邮件添加附件，请在可邮寄类的 build 方法中使用 attach 方法。attach 方法接受文件的完整路径作为第一个参数：

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->attach('/path/to/file');
}

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

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->attach('/path/to/file', [
                    'as' => 'name.pdf',
                    'mime' => 'application/pdf',
                ]);
}

原始数据附件 ​

attachData 方法可用于将原始字节字符串作为附件附加。例如，如果您在内存中生成了一个 PDF 并希望将其附加到电子邮件中而不将其写入磁盘，可以使用此方法。attachData 方法接受原始数据字节作为第一个参数，文件名作为第二个参数，以及选项数组作为第三个参数：

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    return $this->view('emails.orders.shipped')
                ->attachData($this->pdf, 'name.pdf', [
                    'mime' => 'application/pdf',
                ]);
}

内联附件 ​

将内联图像嵌入到电子邮件中通常很麻烦；然而，Laravel 提供了一种方便的方法来将图像附加到电子邮件中并检索适当的 CID。要嵌入内联图像，请在电子邮件模板中使用 $message 变量上的 embed 方法。Laravel 自动将 $message 变量提供给所有电子邮件模板，因此您无需手动传递它：

php
<body>
    这里是一张图片：

    <img src="{{ $message->embed($pathToFile) }}">
</body>
exclamation

$message 变量在 Markdown 消息中不可用。

嵌入原始数据附件 ​

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

php
<body>
    这里是一张来自原始数据的图片：

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

自定义 SwiftMailer 消息 ​

Mailable 基类的 withSwiftMessage 方法允许您注册一个回调，该回调将在发送消息之前使用原始 SwiftMailer 消息实例调用。这为您提供了在消息传递之前自定义消息的机会：

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    $this->view('emails.orders.shipped');

    $this->withSwiftMessage(function ($message) {
        $message->getHeaders()
                ->addTextHeader('Custom-Header', 'HeaderValue');
    });
}

Markdown 可邮寄的类 ​

Markdown 可邮寄消息允许您在可邮寄类中利用邮件通知的预构建模板和组件。由于消息是用 Markdown 编写的，Laravel 能够为消息渲染美观、响应式的 HTML 模板，同时还自动生成纯文本副本。

生成 Markdown 可邮寄的类 ​

要生成带有相应 Markdown 模板的可邮寄类，可以使用 make:mail Artisan 命令的 --markdown 选项：

php
php artisan make:mail OrderShipped --markdown=emails.orders.shipped

然后，在其 build 方法中配置可邮寄类时，调用 markdown 方法而不是 view 方法。markdown 方法接受 Markdown 模板的名称和一个可选的数据数组，以便在模板中使用：

php
/**
 * 构建消息。
 *
 * @return $this
 */
public function build()
{
    return $this->from('example@example.com')
                ->markdown('emails.orders.shipped');
}

编写 Markdown 消息 ​

Markdown 可邮寄类使用 Blade 组件和 Markdown 语法的组合，允许您轻松构建邮件消息，同时利用 Laravel 的预制组件：

php
@component('mail::message')
# 订单已发货

您的订单已发货！

@component('mail::button', ['url' => $url])
查看订单
@endcomponent

谢谢,<br>
{{ config('app.name') }}
@endcomponent
lightbulb

在编写 Markdown 电子邮件时，请勿使用过多缩进。Markdown 解析器会将缩进内容渲染为代码块。

按钮组件 ​

按钮组件渲染一个居中的按钮链接。该组件接受两个参数，一个 url 和一个可选的 color。支持的颜色有 blue、green 和 red。您可以在消息中添加任意数量的按钮组件：

php
@component('mail::button', ['url' => $url, 'color' => 'green'])
查看订单
@endcomponent

面板组件 ​

面板组件将给定的文本块渲染在一个面板中，该面板的背景颜色与消息的其余部分略有不同。这使您可以将注意力集中在给定的文本块上：

php
@component('mail::panel')
这是面板内容。
@endcomponent

表格组件 ​

表格组件允许您将 Markdown 表格转换为 HTML 表格。该组件接受 Markdown 表格作为其内容。表格列对齐支持使用默认的 Markdown 表格对齐语法：

php
@component('mail::table')
| Laravel       | 表格         | 示例  |
| ------------- |:-------------:| --------:|
| 列 2 是      | 居中      |      $10 |
| 列 3 是      | 右对齐 |      $20 |
@endcomponent

自定义组件 ​

您可以将所有 Markdown 邮件组件导出到您自己的应用程序中进行自定义。要导出组件，请使用 vendor:publish Artisan 命令发布 laravel-mail 资产标签：

php
php artisan vendor:publish --tag=laravel-mail

此命令会将 Markdown 邮件组件发布到 resources/views/vendor/mail 目录中。mail 目录将包含一个 html 和一个 markdown 目录，每个目录都包含每个可用组件的各自表示。html 目录中的组件用于生成电子邮件的 HTML 版本，而 markdown 目录中的组件用于生成纯文本版本。您可以自由地自定义这些组件。

自定义 CSS ​

导出组件后，resources/views/vendor/mail/html/themes 目录将包含一个 default.css 文件。您可以自定义此文件中的 CSS，您的样式将自动内联到 Markdown 邮件消息的 HTML 表示中。

lightbulb

如果您想为 Markdown 组件构建一个全新的主题，请在 html/themes 目录中编写一个新的 CSS 文件，并更改 mail 配置文件的 theme 选项。

在浏览器中预览可邮寄的类 ​

在设计可邮寄类的模板时，能够像典型的 Blade 模板一样快速预览渲染的可邮寄类在浏览器中是很方便的。为此，Laravel 允许您直接从路由闭包或控制器返回任何可邮寄类。当返回一个可邮寄类时，它将被渲染并显示在浏览器中，允许您快速预览其设计，而无需将其发送到实际的电子邮件地址：

php
Route::get('/mailable', function () {
    $invoice = App\Invoice::find(1);

    return new App\Mail\InvoicePaid($invoice);
});

发送邮件 ​

要发送消息，请在 Mail facade 上使用 to 方法。to 方法接受一个电子邮件地址、一个用户实例或一个用户集合。如果您传递一个对象或对象集合，邮件程序将自动使用它们的 email 和 name 属性来设置电子邮件收件人，因此请确保这些属性在您的对象上可用。一旦您指定了收件人，您可以将您的可邮寄类实例传递给 send 方法：

php
<?php

namespace App\Http\Controllers;

use App\Order;
use App\Mail\OrderShipped;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Mail;
use App\Http\Controllers\Controller;

class OrderController extends Controller
{
    /**
     * 发货给定的订单。
     *
     * @param  Request  $request
     * @param  int  $orderId
     * @return Response
     */
    public function ship(Request $request, $orderId)
    {
        $order = Order::findOrFail($orderId);

        // 发货订单...

        Mail::to($request->user())->send(new OrderShipped($order));
    }
}

当然，您不仅限于在发送消息时指定“to”收件人。您可以在单个链式方法调用中自由设置“to”、“cc”和“bcc”收件人：

php
Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->send(new OrderShipped($order));

队列邮件 ​

队列邮件消息 ​

由于发送电子邮件消息可能会大大延长应用程序的响应时间，许多开发人员选择将电子邮件消息排队以便在后台发送。Laravel 使用其内置的 统一队列 API 使这变得很容易。要将邮件消息排队，请在指定消息的收件人后使用 Mail facade 上的 queue 方法：

php
Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue(new OrderShipped($order));

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

延迟消息队列 ​

如果您希望延迟队列电子邮件消息的传递，可以使用 later 方法。作为其第一个参数，later 方法接受一个 DateTime 实例，指示消息应何时发送：

php
$when = now()->addMinutes(10);

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->later($when, new OrderShipped($order));

推送到特定队列 ​

由于使用 make:mail 命令生成的所有可邮寄类都使用 Illuminate\Bus\Queueable trait，您可以在任何可邮寄类实例上调用 onQueue 和 onConnection 方法，允许您为消息指定连接和队列名称：

php
$message = (new OrderShipped($order))
                ->onConnection('sqs')
                ->onQueue('emails');

Mail::to($request->user())
    ->cc($moreUsers)
    ->bcc($evenMoreUsers)
    ->queue($message);

默认队列 ​

如果您有希望始终排队的可邮寄类，可以在类上实现 ShouldQueue 合约。现在，即使在发送邮件时调用 send 方法，由于实现了合约，可邮寄类仍将排队：

php
use Illuminate\Contracts\Queue\ShouldQueue;

class OrderShipped extends Mailable implements ShouldQueue
{
    //
}

邮件与本地开发 ​

在开发发送电子邮件的应用程序时，您可能不希望实际将电子邮件发送到真实的电子邮件地址。Laravel 提供了几种方法来在本地开发期间“禁用”实际发送电子邮件。

日志驱动程序 ​

日志邮件驱动程序不会发送您的电子邮件，而是将所有电子邮件消息写入日志文件以供检查。有关按环境配置应用程序的更多信息，请查看 配置文档。

通用收件人 ​

Laravel 提供的另一种解决方案是设置一个通用的电子邮件收件人，以便框架发送的所有电子邮件都将发送到特定地址，而不是发送消息时实际指定的地址。这可以通过在 config/mail.php 配置文件中设置 to 选项来完成：

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

Mailtrap ​

最后，您可以使用像 Mailtrap 这样的服务和 smtp 驱动程序将您的电子邮件消息发送到一个“虚拟”邮箱，您可以在真实的电子邮件客户端中查看它们。这种方法的好处是可以在 Mailtrap 的消息查看器中实际检查最终的电子邮件。

事件 ​

在发送邮件消息的过程中，Laravel 会触发两个事件。在发送消息之前触发 MessageSending 事件，而在消息发送后触发 MessageSent 事件。请记住，这些事件是在邮件被发送时触发的，而不是在其被排队时。您可以在 EventServiceProvider 中为此事件注册事件监听器：

php
/**
 * 应用程序的事件监听器映射。
 *
 * @var array
 */
protected $listen = [
    'Illuminate\Mail\Events\MessageSending' => [
        'App\Listeners\LogSendingMessage',
    ],
    'Illuminate\Mail\Events\MessageSent' => [
        'App\Listeners\LogSentMessage',
    ],
];

版权所有 © 2024-2025 laravel.wiki