Download the PHP package blackfinwebware/laravel-mail-merge without Composer

Blackfin Webware Laravel Mail Merge

This is still beta software. Please use at your own risk. This provides a facility to merge email templates with objects in your system to produce customized emails to individuals or to definable groups. It differs from base Laravel email templating in that it enables you and/or your users to maintain the email content for both repeatable event notification emails as well as for individualized group announcements, and does so in a highly configurable way.

Laravel Framework Compatibility

This has been developed against Laravel 8, but at this point and before getting CI in place, we believe it will work on Laravel from 5.x to 8.x. It does rely upon SwiftMailer currently, and we will be working on Laravel 9.x compatiblity and switching over to Symfony Mailer soon.

Installation

You can install the package via composer:

Migrations

You'll want to publish and run the migrations with:

Views

Optionally, if you'd like to customize the views, you can publish them using

Note that these provide a UI for your Email Templates -- https://yourapp.example.com/mailmerge/email-templates

Groups

When preparing to send an email to a group of people, you'll want to first create and refine a Merge Distribution:

This will create the class App\Mail\Merge\Distribution\MyGroupName.php. The namespace will match your configured namespace.

Edit this to define how to derive the group and, conversely, to work backward to obtain the key related object, or nexus, that will enable the mailmerge to replace macros in your email template.

The nexus object name defined in this class will be used in an attempt to locate an appropriate Macro Expansion class.

See below for a practical example.

Macro Expansions

To define a set of macro expansions (or email template parameters and their substitutions), you'll want to first create a Macro Expansion class.

This will create the class App\Mail\Merge\Macro\MyClassName.php. The namespace will match your configured namespace. You'll edit this class to define the set of macros that you want to use in your email template, and then explcitly how to expand those.

Config

These are the contents of the published config file. Tailor it to your app:

Usage

You can define an EmailTemplate named 'password_reset_request', where your message body might be similar to this:

This is an automated message from the <> System and was triggered by a user action. Someone has requested to have the password reset for the account with the email address of <> and username <>. If this was you, please confirm this by clicking on this link: <> and following the instructions there. This must be done within one week of the initial request or it will no longer work.

If you did not submit this request, please ignore it. If this continues to happen, please report it to <>.

And define in the config where to derive appropriate values for those general use macros:

And then within the linked Macro Expansion Guide, you'd define the macros and what they will expand to when the mailmerge is performed:

You can then call the following method on the facade to produce and send the appropriately populated email:

Advanced

Email Template Type Differentiation

If you are sending out event-driven direct notifications to individual users as well as broadcast emails to groups, it may help to separate these into different tables as the fields could be slightly different, and the roles that interact with these may also be different.

Notifications

• Typically to a single user
• Heavy repetition, static content
• Triggered by an event, automated
• Eg. New User Welcome, Password Reset, Subscription expiration warning, Registration confirmation

Broadcasts

• Typically to a group
• Content a bit more dynamic and time or process sensitive
• Admin or SuperUser initiated
• eg. Conference Abstract Acceptance, App Update News(varying by subscription plan)

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Tom Cowin
• All Contributors

License

The MIT License (MIT). Please see License File for more information.