ideacatlab/laravel-mail-tracker

原始库的个性化版本。

维护者

详细信息

github.com/ideacatlab/laravel-mail-tracker

主页

源代码

问题

安装: 9

依赖项: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 0

开放问题: 0

dev-main 2023-11-26 06:24 UTC

Requires

Requires (Dev)

Suggests

MIT d2379f86fef8ed153742e0359063304d5327edf3

mail-tracker

This package is auto-updated.

Last update: 2024-09-26 08:20:05 UTC

README

Latest Version on Packagist Software License Total Downloads Travis

MailTracker 将挂钩 Laravel 的所有发出的电子邮件，并向其中注入跟踪代码。它还将存储在数据库中渲染的电子邮件。还有一个界面可以查看发送的电子邮件。

注意：如果您正在使用 Laravel 9.x，您必须使用版本 9.6.0 或更高版本。

从 4.x 升级到 5.x

在 4.x 及以前版本中，sent_emails 表中有一个 recipient 列，用于存储 RFC 标准的电子邮件格式 <Name> email@example.com。5.x 已更新为分别存储名称和电子邮件。已从 sent_emails 表迁移中删除了 recipient 和 sender 列，但没有添加迁移来删除这些列。已添加访问器以保留模型的 recipient 和 sender 属性，因此除非您专门查询 sender 或 recipient 列，否则不需要对当前使用这些属性的任何代码进行更新。

要保留升级后的现有数据，请运行 artisan 命令 mail-tracker:migrate-recipients。这将把现有的 recipient 和 sender 数据转换为新的格式。在此之后，您可以删除 recipient 和 sender 列。

在 sent_emails 表中还有一对新属性：opened_at 和 clicked_at。分别存储用户首次打开和点击的时间。这已被添加到默认跟踪索引页。您可以将它添加到您的页面上，或者根据需要使用这些值。

从 3.x 升级到 4.x

从 3.x 升级到 4.x 没有破坏性更改，除了 4.x 仅为 Laravel 7+ 设计。

从 2.x 升级到 3.x

与 3.0 版本的更新相比，有一个破坏性更改，特别是关于触发的事件。如果您正在监听 PermanentBouncedMessageEvent 来捕获所有不可投递的邮件，现在有两个单独的事件：PermanentBouncedMessageEvent 仅在永久退订时触发，而一个新的 ComplaintMessageEvent 将在投诉时触发。还有一个新的 EmailDeliveredEvent 事件，在每次成功投递事件时触发。有关设置 SES/SNS 环境以接收有关这些事件的通知的信息，请参阅下面的文档。

从 2.0 或更早版本升级

首先，通过运行

composer require jdavidbakr/mail-tracker ~2.2

如果您是从早期版本更新的，则需要更新配置文件并运行新的迁移。为了获得最佳结果，请备份 config/mail-tracker.php 文件和 resources/views/vendor/emailTrackingViews 中的视图（如果存在），以恢复任何已定制的值，然后删除该文件并运行

php artisan vendor:publish
php artisan migrate

请注意，sent_emails_url_clicked 表的迁移在版本 2.1.13 中已更改。更改是将 URL 列现在是一个 TEXT 字段，以便允许更长的 URL。如果您有一个旧系统，您可能需要手动更改该列；没有迁移用于执行该更新。

安装

通过 Composer

composer require jdavidbakr/mail-tracker

发布配置文件和迁移

php artisan vendor:publish --provider="jdavidbakr\MailTracker\MailTrackerServiceProvider"

运行迁移

php artisan migrate

注意：如果您想使用不同的连接来存储模型，请在运行迁移之前更新 mail-tracker.php 配置条目 connection。

如果您想使用自己的迁移，可以通过调用 MailTracker::ignoreMigrations() 来跳过此库的迁移。例如：

// In AppServiceProvider

public function boot()
{
    MailTracker::ignoreMigrations();
}

使用方法

安装完成后，所有发出的邮件都将记录到数据库中。以下是在 config/mail-tracker.php 中的配置选项：

  • name：设置您的应用名称。
  • inject-pixel：设置为 true 以将跟踪像素注入到所有发出的 HTML 邮件中。
  • track-links：设置为 true 以重写所有锚点 href 链接以包含跟踪链接。链接会将用户带回到您的网站，然后记录点击后将他们重定向到最终目的地。
  • expire-days：电子邮件在数据库中保留的天数。如果您发送了很多邮件，可能希望它们最终过期。将其设置为 0 以从数据库中永久删除旧邮件。
  • route：跟踪 URL 的路由信息。根据需要设置前缀和中间件。
  • admin-route：管理员的路由信息。设置前缀和中间件。
  • admin-template：管理面板和视图的参数。您可以将现有的管理面板与 MailTracker 管理面板集成。
  • date-format：您可以在管理面板中定义显示日期的格式。
  • content-max-size：您可以通过覆盖默认的最大长度限制来重写 content 数据库字段的长度限制。如果您需要将其变得更长，不要忘记将其类型从 text 更改为其他类型。

如果您不希望跟踪电子邮件，则可以在消息中添加 X-No-Track 头部。将任何随机字符串放入此头部以防止跟踪发生。在发送之前，此头部将从电子邮件中删除。

\Mail::send('email.test', [], function ($message) {
    // ... other settings here
    $message->getHeaders()->addTextHeader('X-No-Track',Str::random(10));
});

在文件系统中存储邮件内容

默认情况下，电子邮件的内容存储在数据库中的 content 列中，以便在发送后可以查看电子邮件。如果发送了很多邮件，这可能会消耗大量内存并减慢数据库的整体性能。您可以在配置中指定将内容保存到文件系统中的文件。

    'log-content-strategy' => 'filesystem',
    'tracker-filesystem' => null
    'tracker-filesystem-folder' => 'mail-tracker',

要使用文件系统，您需要将 log-content-strategy 从 database 更改为 filesystem。您可以使用 tracker-filesystem 指定磁盘，并使用 tracker-filesystem-folder 指定文件存储的文件夹。

覆盖模型

在某些情况下，您可能想要覆盖内置模型。您可以在 AppServiceProvider 中轻松地这样做，例如：

MailTracker::useSentEmailModel(YourOwnSentEmailModel::class);
MailTracker::useSentEmailUrlClickedModel(YourOwnSentEmailUrlClickedModel::class);

您的模型应该实现 SentEmailModel 或 SentEmailUrlClickedModel 接口。此软件包提供了特质，可以轻松实现您自己的模型，而无需重新实现或复制现有代码。

use Illuminate\Database\Eloquent\Model;
use jdavidbakr\MailTracker\Concerns\IsSentEmailModel;
use jdavidbakr\MailTracker\Contracts\SentEmailModel;

class OwnEmailSentModel extends Model implements SentEmailModel {
    use IsSentEmailModel;

    protected static $unguarded = true;

    protected $casts = [
        'meta' => 'collection',
        'opened_at' => 'datetime',
        'clicked_at' => 'datetime',
    ];
}

关于开发测试的说明

有几个人报告说，在测试时跟踪像素不起作用。跟踪像素发生的事情是，电子邮件客户端连接到您的网站以记录查看。为了使这种情况发生，图像必须在客户端可见，并且客户端必须能够连接到您的服务器。

当您处于开发环境时（即使用 Valet 的 .test 域或您计算机上所知的其他域）时，您必须在计算机上有一个电子邮件客户端。这进一步复杂化的是，Gmail 和一些其他基于 Web 的电子邮件客户端不直接连接到图像，而是通过代理连接。那个代理不会连接到您的 .test 域，因此无法正确跟踪电子邮件。我始终建议在发送电子邮件时使用 mailtrap.io 任何开发环境。这不仅解决了问题（mailtrap.io 不会使用代理服务转发电子邮件中的图像），而且还保护您免受意外从测试环境中发送真实电子邮件的风险。

事件

当发送、查看电子邮件或点击链接时，其跟踪信息将通过jdavidbakr\MailTracker\Model\SentEmail模型在数据库中进行计数。此处理通过将作业派发到队列中完成，以防止在电子邮件大发送情况下数据库过载。您可以通过mail-tracker.tracker-queue配置设置选择这些事件通过哪个队列派发，或者将其设置为null以使用默认队列。通过使用非默认队列，您可以优先处理这些跟踪任务以上的应用程序关键任务。

您可能想要对这些事件进行附加处理，因此在这些情况下会触发一个事件

  • jdavidbakr\MailTracker\Events\EmailSentEvent
    • 公共属性sent_email包含SentEmail模型
  • jdavidbakr\MailTracker\Events\ViewEmailEvent
    • 公共属性sent_email包含SentEmail模型
    • 公共属性ip_address包含触发事件的IP地址
  • jdavidbakr\MailTracker\Events\LinkClickedEvent
    • 公共属性sent_email包含SentEmail模型
    • 公共属性ip_address包含触发事件的IP地址
    • 公共属性link_url包含点击的URL

如果您使用Amazon SNS通知系统，这些事件会被触发，以便您可以进行附加处理。

  • jdavidbakr\MailTracker\Events\EmailDeliveredEvent（当您收到“消息已投递”事件时，您可能想要在数据库中将电子邮件标记为“良好”或“已投递”）
    • 公共属性sent_email包含SentEmail模型
    • 公共属性email_address包含触发事件的特定地址
  • jdavidbakr\MailTracker\Events\ComplaintMessageEvent（当您收到投诉时，例如标记为“垃圾邮件”，您可能想要从您的数据库中删除电子邮件）
    • 公共属性sent_email包含SentEmail模型
    • 公共属性email_address包含触发事件的特定地址
  • jdavidbakr\MailTracker\Events\PermanentBouncedMessageEvent（当您收到永久性退信时，您可能想要将电子邮件标记为不良或从数据库中删除）jdavidbakr\MailTracker\Events\TransientBouncedMessageEvent（当您收到暂时性退信时。检查事件的公共属性bounce_sub_type和diagnostic_code以确定在接收到此事件时是否要进行附加处理。）
    • 公共属性sent_email包含SentEmail模型
    • 公共属性email_address包含触发事件的特定地址

要安装事件监听器，您需要创建一个如下所示的文件

<?php

namespace App\Listeners;

use jdavidbakr\MailTracker\Events\ViewEmailEvent;

class EmailViewed
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     *
     * @param  ViewEmailEvent  $event
     * @return void
     */
    public function handle(ViewEmailEvent $event)
    {
        // Access the model using $event->sent_email
        // Access the IP address that triggered the event using $event->ip_address
    }
}
<?php

namespace App\Listeners;

use jdavidbakr\MailTracker\Events\PermanentBouncedMessageEvent;

class BouncedEmail
{
    /**
     * Create the event listener.
     *
     * @return void
     */
    public function __construct()
    {
        //
    }

    /**
     * Handle the event.
     *
     * @param  PermanentBouncedMessageEvent  $event
     * @return void
     */
    public function handle(PermanentBouncedMessageEvent $event)
    {
        // Access the email address using $event->email_address
    }
}

然后，您必须在您的\App\Providers\EventServiceProvider $listen数组中注册您想要处理的事件

/**
 * The event listener mappings for the application.
 *
 * @var array
 */
protected $listen = [
    'jdavidbakr\MailTracker\Events\EmailSentEvent' => [
        'App\Listeners\EmailSent',
    ],
    'jdavidbakr\MailTracker\Events\ViewEmailEvent' => [
        'App\Listeners\EmailViewed',
    ],
    'jdavidbakr\MailTracker\Events\LinkClickedEvent' => [
        'App\Listeners\EmailLinkClicked',
    ],
    'jdavidbakr\MailTracker\Events\EmailDeliveredEvent' => [
        'App\Listeners\EmailDelivered',
    ],
    'jdavidbakr\MailTracker\Events\ComplaintMessageEvent' => [
        'App\Listeners\EmailComplaint',
    ],
    'jdavidbakr\MailTracker\Events\PermanentBouncedMessageEvent' => [
        'App\Listeners\BouncedEmail',
    ],
];

向事件监听器传递数据

通常情况下，您可能需要将发送的电子邮件与其他模型相关联。处理此问题的最佳方法是向您的发件电子邮件添加一个标题，您可以在事件监听器中检索它。以下是一个示例

/**
 * Send an email and do processing on a model with the email
 */
\Mail::send('email.test', [], function ($message) use($email, $subject, $name, $model) {
    $message->from('from@johndoe.com', 'From Name');
    $message->sender('sender@johndoe.com', 'Sender Name');
    $message->to($email, $name);
    $message->subject($subject);

    // Create a custom header that we can later retrieve
    $message->getHeaders()->addTextHeader('X-Model-ID',$model->id);
});

然后在您的事件监听器中

public function handle(EmailSentEvent $event)
{
    $tracker = $event->sent_email;
    $model_id = $event->sent_email->getHeader('X-Model-ID');
    $model = Model::find($model_id);
    // Perform your tracking/linking tasks on $model knowing the SentEmail object
}

请注意，您附加到电子邮件的标题实际上是随消息一起发出的，因此不要存储任何您不希望向您的电子邮件收件人公开的数据。

异常

以下异常可能会抛出。您可以将它们添加到您的异常处理程序的忽略列表中，或者按您的要求处理它们。

  • jdavidbakr\MailTracker\Exceptions\BadUrlLink - URL链接出现了一些问题。基本上，系统无法正确解析URL链接以发送重定向。

Amazon SES功能

如果您使用Amazon SES，您可以向跟踪添加一些附加信息。要设置SES回调，首先在SES控制面板中的您的域下设置SES通知。然后通过转到通知主题的管理面板并为您从管理页面复制的URL创建一个订阅来订阅主题。系统应立即响应该订阅请求。如果您喜欢，您可以使用多个订阅（即一个用于投递，一个用于退信）。请参阅上面的失败消息触发的事件。为了增加安全性，建议将主题ARN设置为mail-tracker配置。

视图

当您运行php artisan vendor:publish命令时，简单的视图将添加到您的资源/views/vendor/emailTrakingViews中，您可以对其进行自定义。当然，您也可以从头开始构建整个管理页面，使用这些视图作为指南。

管理面板

MailTracker 内置了管理区域。与软件包一起发布的默认配置将其置于 can:see-sent-emails 中间件之后；您可以为此规则创建一个网关或将其更改为使用您自己的中间件。您还可以更改默认前缀以及完全禁用管理路由。

路由名称为 'mailTracker_Index'。标准管理面板路由位于 /email-manager。您可以使用路由名称将它们包含到现有的管理菜单中。您可以在配置文件中自定义您的路由。您可以查看所有已发送的电子邮件、总打开次数、总点击次数，显示单个电子邮件以及显示点击的URL详情。

所有视图（电子邮件模板、面板）都可以在 resources/views/vendor/emailTrakingViews 中进行自定义。

贡献

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

安全

如果您发现任何与安全相关的问题，请通过电子邮件 me@jdavidbaker.com 联系我，而不是使用问题跟踪器。

鸣谢

许可证

MIT 许可证（MIT）。有关更多信息，请参阅 许可证文件。