Download the PHP package spatie/laravel-database-mail-templates without Composer

Render Laravel mailables based on a mail template stored in the database

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.

The HTML for the sent email will look like this:

Installation

You can install the package via composer:

Publish and run the database 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:

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:

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:

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:

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:

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().

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.

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

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.

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:

Testing

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 [email protected] instead of using the issue tracker.

Credits

• Alex Vanderbist
• All Contributors

License

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