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',
        // ...
    ],
    // ...
],

注册预览中间件路由

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

// 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：已发送邮件的EML版本路径

对已发送邮件进行断言

目前，使用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)：返回布尔值

更新日志

请参阅更新日志以获取有关最近更改的更多信息。

升级

请参阅升级指南了解如何从themsaid/laravel-mail-preview迁移，以及如何升级到新的大版本。

贡献

请参阅贡献指南以获取详细信息。

安全漏洞

请查阅我们的安全策略了解如何报告安全漏洞。

鸣谢

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

许可证

MIT许可证（MIT）。请参阅许可证文件获取更多信息。

themsaid / laravel-mail-preview

维护者

详细信息