spatie/laravel-database-mail-templates

Render Laravel mailables using a template stored in the database.

3.7.0 2024-10-03 14:50 UTC

Requires

• php: ^7.2|^8.0
• laravel/framework: ~5.8|^6.0|^7.0|^8.0|^9.0|^10.0|^11.0
• mustache/mustache: ^2.14.1|^2.14

Requires (Dev)

• ext-pdo_sqlite: *
• mockery/mockery: ^1.0|^1.3.1
• orchestra/testbench: ~3.8|^4.0|^5.0|^6.0|^7.0|^8.0|^9.0
• phpunit/phpunit: ^7.5|^8.0|^9.3|^10.5

MIT

• Alex Vanderbist

• spatie
• laravel-database-mail-templates

README

Render Laravel mailables using a template stored in the database.

Support us

We invest a lot of resources into creating best in class open source packages. You can support us by buying one of our paid products.

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on our contact page. We publish all received postcards on our virtual postcard wall.

Quick example

The following example will send a WelcomeMail using a template stored in the database and wrapped in an HTML layout.

namespace App\Mail;

use Spatie\MailTemplates\TemplateMailable;

class WelcomeMail extends TemplateMailable
{
    /** @var string */
    public $name;

    public function __construct(User $user)
    {
        $this->name = $user->name;
    }
    
    public function getHtmlLayout(): string
    {
        $pathToLayout = storage_path('mail-layouts/main.html');
    
        return file_get_contents($pathToLayout);
    }
}

MailTemplate::create([
    'mailable' => \App\Mail\WelcomeMail::class,
    'subject' => 'Welcome, {{ name }}',
    'html_template' => '<p>Hello, {{ name }}.</p>',
    'text_template' => 'Hello, {{ name }}.'
]);

Mail::to($user->email)->send(new WelcomeMail($user));

The HTML for the sent email will look like this:

<header>Welcome!</header>
<p>Hello, John.</p>
<footer>Copyright 2018</footer>

Installation

You can install the package via composer:

composer require spatie/laravel-database-mail-templates

Publish and run the database migrations:

php artisan vendor:publish --provider="Spatie\MailTemplates\MailTemplatesServiceProvider" --tag="migrations"

If you want to use the default MailTemplate model, all that's left to do is run php artisan migrate to create the mail_templates table.

If you plan on creating a custom MailTemplate model continue by modifying the migration and creating your custom model before running php artisan migrate.

Usage

After installing the package and running the migrations you'll have a new table in your database called mail_templates. This table will be used by the MailTemplate model.

The default MailTemplate has a mailable property that corresponds to the Mailable's class name. It also has a subject and body property which are both used to store mustache template strings.

You might want to set up a seeder that seeds your application's necessary templates:

use Illuminate\Database\Seeder;

class MailTemplatesSeeder extends Seeder
{
    public function run()
    {
        MailTemplate::create([
            'mailable' => \App\Mail\WelcomeMail::class,
            'subject' => 'Welcome, {{ name }}',
            'html_template' => '<h1>Hello, {{ name }}!</h1>',
            'text_template' => 'Hello, {{ name }}!',
        ]);
    }
}

As you can see in the above example, you can use mustache template tags in both the subject and body of the mail template!

Let's have a look at the corresponding mailable:

namespace App\Mail;

use TemplateMailable;

class WelcomeMail extends TemplateMailable
{
    /** @var string */
    public $name;
    
    /** @var string */
    public $email;

    public function __construct(User $user)
    {
        $this->name = $user->name;
        $this->email = $user->email;
    }
}

By extending the \Spatie\MailTemplates\TemplateMailable class this mailable will be rendered using the corresponding MailTemplate. All public properties on the WelcomeMail will be available in the template.

If you need to use properties within your template that are initially defined within your WelcomeMail (for example, data that comes from another source). You can call $this->setAdditionalData() and pass it an array of you additional key => value pairs.

An example of this would be:

namespace App\Mail;

use TemplateMailable;

class WelcomeMail extends TemplateMailable
{

    public function __construct(User $user)
    {
        $this->setAdditionalData([
            'name' => 'Joe Bloggs'
        ]);
    }
}

Customizing the MailTemplate model

The default MailTemplate model is sufficient for using one database mail template for one mailable. If you want to use multiple mail templates for the same mailable or extend the MailTemplate model, we highly encourage you to publish the mail_template migration and create your own mail template model by extending MailTemplate. Make sure to implement the MailTemplateInterface interface as well.

Imagine an application like meetup.com that deals with different meetup groups. The application has a couple of different mailables like NewMeetupPlannedMail and MeetupCancelledMail to inform users of new meetups. Using this package we can create a MeetupMailTemplate for each meetup group. This way each group can add their own copy in the template. The MeetupMailTemplate model would look something like this:

use Spatie\MailTemplates\Models\MailTemplate;

class MeetupMailTemplate extends MailTemplate implements MailTemplateInterface
{
    public function meetupGroup(): BelongsTo
    {
        return $this->belongsTo(MeetupGroup::class);
    }
    
    public function scopeForMailable(Builder $query, Mailable $mailable): Builder
    {
        return $query
            ->where('mailable', get_class($mailable))
            ->where('meetup_group_id', $mailable->getMeetupGroupId());
    }
    
    public function getHtmlLayout(): string
    {
        return $this->meetupGroup->mail_layout;
    }
}

MeetupMailTemplate extends the package's MailTemplate and overrides a couple of methods. We've also added the relationship to the MeetupGroup that this mail template belongs to.

By extending the getHtmlLayout() method we can provide the group's custom mail header and footer. Read more about adding a header and footer to a mail template.

We've also extended the scopeForMailable() method which is used to fetch the corresponding mail template from the database. On top of the default mailable where-clause we've added a meetup_group_id where-clause that'll query for the mailable's meeting_group_id.

Next, let's have a look at what our NewMeetupPlannedMail might look like:

use Spatie\MailTemplates\TemplateMailable;

class NewMeetupPlannedMail extends TemplateMailable
{
    // use our custom mail template model
    protected static $templateModelClass = MeetupMailTemplate::class;

    /** @var string */
    public $location;
    
    /** @var \App\Models\Meetup */
    protected $meetup; // protected property, we don't want this in the template data

    public function __construct(Meetup $meetup)
    {
        $this->meetup = $meetup;
        $this->location = $meetup->location;
    }
    
    // provide a method to get the meetup group id so we can use it in MeetupMailTemplate
    public function getMeetupGroupId(): int
    {
        return $this->meetup->meetup_group_id;
    }  
}

When sending a NewMeetupPlannedMail the right MeetupMailTemplate for the meetup group will be used with its own custom copy and mail layout. Pretty neat.

Template variables

When building a UI for your mail templates you'll probably want to show a list of available variables near your wysiwyg-editor. You can get the list of available variables from both the mailable and the mail template model using the getVariables().

WelcomeMail::getVariables();
// ['name', 'email']

MailTemplate::create(['mailable' => WelcomeMail::class, ... ])->getVariables();
// ['name', 'email']

MailTemplate::create(['mailable' => WelcomeMail::class, ... ])->variables;
// ['name', 'email']

Adding a header and footer around a mail template

You can extend the getHtmlLayout() method on either a template mailable or a mail template. getHtmlLayout() should return a string layout containing the {{{ body }}} placeholder.

When sending a TemplateMailable the compiled template will be rendered inside of the {{{ body }}} placeholder in the layout before being sent.

If using a Blade view, the placeholder will need to be @{{{ body }}}.

The following example will send a WelcomeMail using a template wrapped in a layout.

use Spatie\MailTemplates\TemplateMailable;

class WelcomeMail extends TemplateMailable
{
    // ...
    
    public function getHtmlLayout(): string
    {
        /**
         * In your application you might want to fetch the layout from an external file or Blade view.
         * 
         * External file: `return file_get_contents(storage_path('mail-layouts/main.html'));`
         * 
         * Blade view: `return view('mailLayouts.main', $data)->render();`
         */
        
        return '<header>Site name!</header>{{{ body }}}<footer>Copyright 2018</footer>';
    }
}

MailTemplate::create([
    'mailable' => WelcomeMail::class,
    'html_template' => '<p>Welcome, {{ name }}!</p>', 
]);

Mail::to($user->email)->send(new WelcomeMail($user));

The rendered HTML for the sent email will look like this:

<header>Site name!</header>
<p>Welcome, John!</p>
<footer>Copyright 2018</footer>

Adding a layout to a mail template model

It is also possible to extend the getHtmlLayout() method of the MailTemplate model (instead of extending getHtmlLayout()on the mailable).

You might for example want to use a different layout based on a mail template model property. This can be done by adding the getHtmlLayout() method on your custom MailTemplate model instead.

The following example uses a different layout based on what EventMailTemplate is being used. As you can see, in this case the layout is stored in the database on a related Event model.

use Spatie\MailTemplates\Models\MailTemplate;

class EventMailTemplate extends MailTemplate
{
    public function event(): BelongsTo
    {
        return $this->belongsTo(Event::class);
    }

    public function getHtmlLayout(): string
    {
        return $this->event->mail_layout_html;
    }
}

Translating mail templates

Out of the box this package doesn't support multi-langual templates. However, it integrates perfectly with Laravel's localized mailables and our own laravel-translatable package.

Simply install the laravel-translatable package, publish the create_mail_template_table migration, change its text columns to json and extend the MailTemplate model like this:

use \Spatie\MailTemplates\MailTemplate;

class MailTemplate extends MailTemplate
{
    use HasTranslations;
    
    public $translatable = ['subject', 'html_template'];
}

Testing

composer test

Changelog

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

Contributing

Please see CONTRIBUTING for details.

Security

If you've found a bug regarding security please mail [e-mail] instead of using the issue tracker.

Credits

• Alex Vanderbist
• All Contributors

License

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