Laravel Mailator provides a featherweight system for configuring email schedulers and email templates based on application events.

Installation

You can install this package via composer:

composer require binarcode/laravel-mailator

Publish

Publish migrations: a vendor:publish --tag=mailator-migrations

Publish config: a vendor:publish --tag=mailator-config

Usage

It has mainly 2 directions of usage:

1. Schedule emails sending (or actions triggering)
2. Email Templates & Placeholders

Scheduler

To set up a mail to be sent after or before an event, you can do this by using the Scheduler facade.

Here is an example of how to send the invoice reminder email 3 days before the $invoice->due_date:

use Binarcode\LaravelMailator\Tests\Fixtures\InvoiceReminderMailable;
use Binarcode\LaravelMailator\Tests\Fixtures\SerializedConditionCondition;

Binarcode\LaravelMailator\Scheduler::init('Invoice reminder.')
    ->mailable(new InvoiceReminderMailable($invoice))
    ->recipients('foo@binarcode.com', 'baz@binarcode.com')
    ->constraint(new SerializedConditionCondition($invoice))
    ->days(3)
    ->before($invoice->due_date)
    ->save();

Constraint

The contraint() method accept an instance of Binarcode\LaravelMailator\Constraints\SendScheduleConstraint. Each constraint will be called when the scheduler will try to send the email. If all constraints return true, the email will be sent.

The constraint() method could be called many times, and each constraint will be stored.

Since each constraint will be serialized, it’s very indicated to use Illuminate\Queue\SerializesModels trait, so the serialized models will be loaded properly, and the data stored in your storage system will be much less.

Let’s assume we have this

BeforeInvoiceExpiresConstraint constraint:

class BeforeInvoiceExpiresConstraint implements SendScheduleConstraint
{
    public function canSend(MailatorSchedule $mailatorSchedule, Collection $log): bool
    {
        // your conditions
        return true;
    }
}

Action

Using Scheduler you can even define your custom action:

$scheduler = Scheduler::init('Invoice reminder.')
    ->days(1)
    ->before(now()->addWeek())
    ->actionClass(CustomAction::class)
    ->save();

The CustomAction should implement the Binarcode\LaravelMailator\Actions\Action class.

Templating

To create an email template:

$template = Binarcode\LaravelMailator\Models\MailTemplate::create([
    'name' => 'Welcome Email.',
    'from_email' => 'from@bar.com',
    'from_name' => 'From Bar',
    'subject' => 'Welcome to Mailator.',
    'html' => '<h1>Welcome to the party!</h1>',
]);

Adding some placeholders with descriptions to this template:

$template->placeholders()->create(
    [
        'name' => '::name::',
        'description' => 'Name',
    ],
);

To use the template, you simply have to add the WithMailTemplate trait to your mailable.

This will enforce you to implement the getReplacers method, this should return an array of replacers to your template. The array may contain instances of Binarcode\LaravelMailator\Replacers\Replacer or even Closure instances.

Mailator ships with a built-in replacer ModelAttributesReplacer, it will automatically replace attributes from the model you provide to placeholders.

The last step is how to say to your mailable what template to use. This could be done in the build method as shown below:

class WelcomeMailatorMailable extends Mailable
{
    use Binarcode\LaravelMailator\Support\WithMailTemplate;
    
    private Model $user;
    
    public function __construct(Model $user)
    {
        $this->user = $user;
    }
    
    public function build()
    {
        return $this->template(MailTemplate::firstWhere('name', 'Welcome Email.'));
    }

    public function getReplacers(): array
    {
        return [
            Binarcode\LaravelMailator\Replacers\ModelAttributesReplacer::makeWithModel($this->user),

            function($html) {
                //
            }       
        ];
    }
}

For more details about this package, Visit Github.