README

此包可以在发送邮件时显示一个小覆盖层。覆盖层包含一个指向刚发送的邮件的链接。

这在测试本地环境中的邮件时非常有用。

支持我们

我们投入了大量资源来创建最佳开源包。您可以通过购买我们的付费产品之一来支持我们。

我们非常感谢您从家乡寄给我们明信片，并说明您正在使用我们哪些包。您可以在我们的联系页面上找到我们的地址。我们将所有收到的明信片发布在我们的虚拟明信片墙上。

安装

您可以通过 composer 安装此包

composer require spatie/laravel-mail-preview

配置邮件传输

此包包含一个名为 preview 的邮件传输。我们建议只在非生产环境中使用此传输。要使用 preview 传输，请在您的 config/mail.php 文件中将 mailers.smtp.transport 更改为 preview。

// in config/mail.php

'mailers' => [
    'smtp' => [
        'transport' => 'preview',
        // ...
    ],
    // ...
],

注册预览中间件路由

此包可以在邮件发送时显示发送邮件的链接。要使用此功能，您必须将 Spatie\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse 中间件添加到您的内核中的 web 中间件组。

// in app/Http/Kernel.php

protected $middlewareGroups = [
    'web' => [
        // other middleware
        
        \Spatie\MailPreview\Http\Middleware\AddMailPreviewOverlayToResponse::class,
    ],
    
    // ...
];

您还必须将 mailPreview 添加到您的路由文件中。通常，路由文件位于 routes/web.php。

// in routes/web.php

Route::mailPreview();

这将注册一个在 /spatie-mail-preview 显示发送邮件的路由。要自定义 URL，请将您想要的 URL 传递给宏。

Route::mailPreview('custom-url-where-sent-mails-will-be-shown');

发布配置文件

可选地，您可以使用以下命令发布配置文件

php artisan vendor:publish --provider="Spatie\MailPreview\MailPreviewServiceProvider" --tag="mail-preview-config"

这是将在 config/mail-preview.php 发布的配置文件内容

return [
    /*
     * By default, the overlay will only be shown and mail will only be stored
     * when the application is in debug mode.
     */
    'enabled' => env('APP_DEBUG', false),

    /*
     * All mails will be stored in the given directory.
     */
    'storage_path' => storage_path('email-previews'),

    /*
     * This option determines how long generated preview files will be kept.
     */
    'maximum_lifetime_in_seconds' => 60,

    /*
     * When enabled, a link to mail will be added to the response
     * every time a mail is sent.
     */
    'show_link_to_preview' => true,

    /*
     * Determines how long the preview pop up should remain visible.
     *
     * Set this to `false` if the popup should stay visible.
     */
    'popup_timeout_in_seconds' => 8,
    
    /**
     * Determines the date format used for the file names.
     *
     * The default 'u' stands for microseconds.
     */
    'filename_date_format' => 'u',
];

发布视图

可选地，您可以发布渲染预览覆盖层和邮件本身的视图。

php artisan vendor:publish --provider="Spatie\MailPreview\MailPreviewServiceProvider" --tag="mail-preview-views"

您可以根据需要修改将在 resources/views/vendor/mail-preview 发布的视图。

用法

每次发送电子邮件时，都会在 mail-preview 配置文件中指定的 storage_path 目录中保存一个 .html 和 .eml 文件。文件名包括第一个收件人和主题。

1457904864_john_at_example_com_invoice_000234.html
1457904864_john_at_example_com_invoice_000234.eml

您可以在网络浏览器中打开 .html 文件。在您的默认电子邮件客户端中打开 .eml 文件以获得最终输出的真实外观。

在网络浏览器中预览

当您在网络浏览器中打开 .html 文件时，您将能够看到您的电子邮件将如何显示。

在生成的文件开头，您将找到一个包含所有消息信息的 HTML 注释

<!--
From:{"info@acme.com":"Acme HQ"},
to:{"jack@gmail.com":"Jack Black"},
reply-to:{"info@acme.com"},
cc:[{"finance@acme.com":"Acme Finance"}, {"management@acme.com":"Acme Management"}],
bcc:null,
subject:Invoice #000234
-->

事件

每次将邮件存储在磁盘上时，都会触发 Spatie\MailPreview\Events\MailStoredEvent 事件。它有三个公共属性

message：一个 Swift_Mime_SimpleMessage 实例
pathToHtmlVersion：发送邮件的 HTML 版本的路径
pathToEmlVersion：发送邮件的电子邮件版本路径

对发送的邮件进行断言

目前，使用Laravel的Mail::fake，您无法对邮件内容进行断言，因为使用模拟将不会渲染邮件。

该包提供的SentMails外观允许您对内容进行断言。

这允许您在不将邮件类放在作用域内的情况下对邮件内容进行断言。

// in a test

Artisan::call(CommandThatSendsMail::class);

Spatie\MailPreview\Facades\SentMails::assertLastContains('something in your mail');

让我们以这个邮件类为例，解释其他可用的断言方法。

namespace App\Mail;

use Illuminate\Mail\Mailable;

class MyNewSongMailable extends Mailable
{
    public function build()
    {
        $this
            ->to('ringo@example.com')
            ->cc('paul@examle.com')
            ->bcc('john@examle.com')
            ->subject('Here comes the sun')
            ->html("It's been a long cold lonely winter");
    }
}

在您的代码中，您可以使用以下方式发送该邮件类

Mail::send(new MyNewSongMailable());

在您的测试中，您可以使用assertSent函数断言邮件已发送。您应该向assertSent传递一个可调用对象，该对象将获得一个SentMail实例。每个已发送的邮件都将传递给可调用对象。如果可调用对象返回true，则断言通过。

use Spatie\MailPreview\Facades\SentMails;
use \Spatie\MailPreview\SentMails\SentMail;

SentMails::assertSent(fn (SentMail $mail) => $mail->bodyContains('winter')); // will pass
SentMails::assertSent(fn (SentMail $mail) => $mail->bodyContains('spring')); // will not pass

您可以在SentMail上使用任意多的断言方法。

SentMails::assertSent(function (SentMail $mail)  {
    return
        $mail->subjectContains('sun') &&
        $mail->hasTo('ringo@example.com')
        $mail->bodyContains('winter');

Spatie\MailPreview\Facades\SentMails具有以下断言方法

assertCount(int $expectedCount)：断言发送了多少封邮件
assertLastContains(string $expectedSubstring)：断言最后一封发送的邮件的内容包含指定的子串
assertSent($findMailCallable, int $expectedCount = 1)：如上所述
assertTimesSent(int $expectedCount, Closure $findMail)
assertNotSent(Closure $findMail)

此外，Spatie\MailPreview\Facades\SentMails还有以下方法

all：返回一个包含已发送邮件的数组。每个项目都将是一个sentMail实例
count()：返回发送的邮件数量
last：返回最后一封发送的邮件的SentMail实例。如果没有发送邮件，则返回null。
lastContains：如果最后一封发送的邮件的内容包含指定的子串，则返回true
timesSent($findMailCallable)：返回发送的邮件数量，这些邮件通过了给定的可调用对象

sentMail类提供以下断言

assertSubjectContains($expectedSubstring)
assertFrom($expectedAddress)
assertTo$expectedAddress)
assertCc($expectedAddress)
assertBcc($expectedAddress)
assertContains($substring)：如果邮件的内容包含子串，则通过

此外，sentMail包含以下方法

subject()：返回邮件的主题
to()：返回所有收件人作为数组
cc()：返回所有抄送收件人作为数组
bcc()：返回所有密送收件人作为数组
body()：返回邮件的内容
subjectContains)：返回布尔值
hasFrom($expectedAddress)：返回布尔值
hasTo($expectedAddress)：返回布尔值
hasCc($expectedAddress)：返回布尔值
hasBcc($expectedAddress)：返回布尔值

变更日志

有关最近更改的更多信息，请参阅CHANGELOG。

升级

有关如何从themsaid/laravel-mail-preview切换以及如何升级到更高版本的信息，请参阅UPGRADING。

贡献

有关详细信息，请参阅CONTRIBUTING。

安全漏洞

有关如何报告安全漏洞的信息，请参阅我们的安全策略。

鸣谢

此包的初始版本由Mohamed Said创建，他慷慨地将此包托付给我们Spatie。

许可证

麻省理工学院许可证（MIT）。请参阅许可证文件获取更多信息。

spatie / laravel-mail-preview

维护者

详情