README

这是一款仍在测试阶段的软件。请在自己的风险下使用。它提供了一种将系统中的对象与电子邮件模板合并的功能，以向个人或定义的群体发送定制的电子邮件。与基本的 Laravel 电子邮件模板不同，它允许您和/或您的用户以高度可配置的方式维护重复事件通知电子邮件以及个性化群体公告的电子邮件内容。

Laravel 框架兼容性

该软件是在 Laravel 8 上开发的，但在此之前和在建立 CI 之前，我们认为它将在 5.x 到 8.x 的 Laravel 上运行。它目前依赖于 SwiftMailer，我们将致力于 Laravel 9.x 兼容性，并很快切换到 Symfony Mailer。

安装

您可以通过 composer 安装此包

composer require blackfinwebware/laravel-mail-merge

迁移

您需要使用以下命令发布并运行迁移

php artisan vendor:publish --tag="laravel-mail-merge-migrations"
php artisan migrate

视图

如果您想自定义视图，可以使用以下命令发布它们

php artisan vendor:publish --tag="laravel-mail-merge-views"

请注意，这些提供了电子邮件模板的用户界面 -- https://yourapp.example.com/mailmerge/email-templates

组

在准备向一组人发送电子邮件之前，您需要首先创建和细化合并分发

php artisan make:mergeDistribution MyGroupName

这将创建名为 App\Mail\Merge\Distribution\MyGroupName.php 的类。命名空间将与您配置的命名空间匹配。

编辑此文件以定义如何推导出组，以及如何反向获取相关对象或键，这将使邮件合并能够在电子邮件模板中替换宏。

此类中定义的枢纽对象名称将用于尝试定位适当的宏扩展类。

下面是一个实际示例。

宏扩展

要定义一组宏扩展（或电子邮件模板参数及其替换），您首先需要创建一个宏扩展类。

php artisan make:macroExpansion MyClassName

这将创建一个名为 App\Mail\Merge\Macro\MyClassName.php 的类。命名空间将与您配置的命名空间匹配。您需要编辑此类以定义您想在电子邮件模板中使用的宏集合，以及如何明确地扩展它们。

配置

这是已发布配置文件的内容。根据您的应用程序进行定制。

return [
    /*
    |--------------------------------------------------------------------------
    | Namespace
    |--------------------------------------------------------------------------
    | To integrate the mailmerge package, there will be some classes you'll need to create in your app to identify
    | Groups and Macro Sets(see below). This parameter provides you with the ability to customize your root namespace
    | for these classes. Note that if you change it here, you'll need to change it wherever it appears in this file, 
    | and remember to clear your config cache after making changes in this file.
    */

    'namespace' => 'App\\Mail\\Merge',

    /*
    |--------------------------------------------------------------------------
    | Tables
    |--------------------------------------------------------------------------
    | Tables needed to support the package. At the least we need the EmailTemplates table
    | which corresponds with our EmailTemplate model.
    */

    'tables' => ['email_templates' => 'mailmerge_email_templates'],

    /*
    |--------------------------------------------------------------------------
    | Groups
    |--------------------------------------------------------------------------
    | Groups here are those that can be identified as intended targets of an email merge. Each group
    | must be identified with a Merge Distribution class. This serves two functions: 1) it provides a way to get a
    | recipient list and 2) a way to reverse that and find the instance of our nexus object related to each
    | recipient. This nexus object is what will provide the values for the macro expansions - typically this is
    | a specific model in your app that is related directly or indirectly to a user, but is traversable from the
    | user so that macro values can be discovered and expanded quickly for each user.
    */

    'groups' => ['GroupName' => App\Mail\Merge\Distribution\GroupNameMergeDistribution::class],

    /*
    |--------------------------------------------------------------------------
    | Macro Sets
    |--------------------------------------------------------------------------
    | Macros are grouped in sets by like function. They may be related to a specific model or process which we refer to
    | as a nexus here. The General macros are applied to all outbound emails. Those defined within a Macro Expansion
    | Guide are application specific where the Guide provides a map to expand each macro appropriately for the
    | recipient.
    */

    'macro_sets' => ['general' => ['app_name' => env('APP_NAME', 'MyApp'),
                                   'primary_contact_email' => 'taylor@laravel.com'],
                     'macro_set_name' => App\Mail\Merge\Macro\ModelNameMacroExpansionGuide::class],

    /*
    |--------------------------------------------------------------------------
    | Queue outbound email
    |--------------------------------------------------------------------------
    | Queue mail when sending -- this allows the actual send to be handled asynchronously and is much preferred.
    | You must have queueing configured in your system.
    */

    'use_queues' => true,

    /*
    |--------------------------------------------------------------------------
    | Debug
    |--------------------------------------------------------------------------
    | Used within the package to provide more debugging info to the log, and other items. If true, the primary
    | admin email will get bcc'd on outbound emails when in production and sandbox is false.
    */

    'debug' => true,

    /*
    |--------------------------------------------------------------------------
    | Sandbox Email
    |--------------------------------------------------------------------------
    | If true, when your app is not in production OR you have debug set to true, it will send all the generated
    | messages to the primary_admin_email, and NOT to the intended recipient(s).
    */

    'sandbox_email' => true,
    'primary_admin_email' => env('MAIL_FROM_ADDRESS', 'sysadmin@example.com'),

    /*
    |--------------------------------------------------------------------------
    | UI App Layout
    |--------------------------------------------------------------------------
    | App layout template. This is initially populated with a minimalist package layout for demo / test of the
    | provided package UI, using Bootstrap 4.6. Hint: to use your own layout, you may just need to remove the
    | 'mailmerge::'.
    */

    'blade_layout' => 'mailmerge::layouts.app',

    /*
    |--------------------------------------------------------------------------
    | Route prefix
    |--------------------------------------------------------------------------
    | If you want package provided routes to have a prefix so they are set apart from you main application, you
    | can leave this at the default or modify as appropriate.
    */

    'route_prefix' => 'mailmerge',

    /*
    |--------------------------------------------------------------------------
    | Route middleware groups
    |--------------------------------------------------------------------------
    | Wrap the routes in the web middleware so that they run through the normal Laravel processes. You may want to use
    | the 'auth' middleware group as well if you are protecting your routes with a login layer.
    */

    'middleware' => ['web'],

    /*
    |--------------------------------------------------------------------------
    | Advanced
    |--------------------------------------------------------------------------
    | If you have enough differentiation between your notification and broadcast emails,
    | and/or have different user roles that are maintaining these, you can specify their
    | classnames here. Note that they must extend BlackfinWebware\LaravelMailMerge\Models\EmailTemplate
    |
    | 'notification_email_class' => App\Models\NotificationEmailTemplate::class,
    | 'broadcast_email_class' => App\Models\BroadcastEmailTemplate::class,
    */
];

用法

您可以定义一个名为 'password_reset_request' 的 EmailTemplate，其中消息体可能如下所示

这是来自 <<app_name>> 系统的自动消息，由用户操作触发。有人请求重置具有电子邮件地址 <<password_reset_request_email>> 和用户名 <<member_username>> 的账户的密码。如果您是本人，请通过单击此链接：<<password_reset_link>> 并遵循那里的说明进行确认。必须在初始请求后一周内完成此操作，否则将不再有效。

如果您没有提交此请求，请忽略。如果这种情况继续发生，请向 <<primary_contact_email>> 报告。

然后在配置中定义，如何为这些通用宏导出适当的值。

'macro_sets' = ['general' => ['app_name' => env('APP_NAME', 'MyApp'),
                         'primary_contact_email' => 'joe_user@example.com'],
                         'password_reset_request' => App\Mail\Merge\Macro\PasswordResetRequestMacroExpansionGuide::class];

然后，在链接的宏扩展指南中，您将定义宏以及执行邮件合并时它们将扩展成什么。

public function expansions(){
        $password_reset_link = url("/password_reset_request/reset/" . $this->objects['password_reset_request']->reset_access_token);

        return ['password_reset_request_email' => $this->objects['password_reset_request']->email,
                'member_username' => $this->objects['password_reset_request']->user->username,
                'password_reset_link' => $password_reset_link];
    }

然后您可以在外观类上调用以下方法，生成并发送适当填充的电子邮件。

Mailmerge::composeAndSend('password_reset_request', $password_reset_request);

高级

电子邮件模板类型区分

如果您正在向个人用户发送事件驱动的直接通知，以及向群体发送广播电子邮件，将它们分离到不同的表中可能会有所帮助，因为这些字段可能略有不同，与之交互的角色也可能不同。

通知

通常针对单个用户
重复率高，内容静态
由事件触发，自动执行
例如：新用户欢迎，密码重置，订阅过期警告，注册确认

广播

通常针对群体
内容略为动态，与时间或过程敏感
由管理员或超级用户发起
例如：会议摘要接受，应用更新新闻（根据订阅计划变化）

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

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

致谢

许可证

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

blackfinwebware / laravel-mail-merge

维护者

详细信息

README

Laravel 框架兼容性

安装

迁移

视图

组

宏扩展

配置

用法

高级

电子邮件模板类型区分

通知

广播

测试

变更日志

贡献

安全漏洞

致谢

许可证