Laravel Database Mail Templates

To use database-stored templates, extend the \Spatie\MailTemplates\TemplateMailable class in your Laravel Mailable.

By default, the package looks for a record in the mail_templates table where the mailable column matches your class name. All public properties on your Mailable class are automatically available as variables in your Mustache templates.

If you need to pass data that isn't a public property, use the setAdditionalData() method in your constructor.

namespace App\Mail;

use Spatie\MailTemplates\TemplateMailable;

class WelcomeMail extends TemplateMailable
{
    /** @var string */
    public $name;
    
    public function __construct($user)
    {
        $this->name = $user->name;
        // For data not stored in a public property:
        $this->setAdditionalData([
            'extra_info' => 'some value'
        ]);
    }
}

The package does not support multi-language templates natively, but it is compatible with spatie/laravel-translatable.

To enable it:

1. Install spatie/laravel-translatable.
2. Publish the create_mail_template_table migration.
3. Modify the migration to change subject and html_template columns from text to json.
4. Extend the MailTemplate model and use the HasTranslations trait, defining the translatable fields in the $translatable array.

use Spatie\Translatable\HasTranslations;

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

Upgrading from version 2.x.x to 3.0.0 requires database schema updates and changes to custom implementation interfaces.

Database Changes

The default migration has changed. You must manually update your database or create a new migration to apply these changes:

1. Rename the template column to html_template.
2. Add a new nullable text_template column.

Custom MailTemplateModel Changes

If you implement a custom model using MailTemplateInterface, the method signatures have changed to support text templates and avoid collisions with Laravel Nova. Replace the old methods with the new ones:

• Replace subject() with getSubject()
• Replace template() with getHtmlTemplate()
• Add getTextTemplate()

Custom TemplateMailable Changes

If you are using a custom TemplateMailable, rename the $templateModel property to $templateModelClass.

Install the package via Composer and publish the migrations to set up the necessary database tables.

1. Install the package:

composer require spatie/laravel-database-mail-templates

2. Publish the migrations:

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

3. Run the migrations:

php artisan migrate

To identify which variables are available for use in a Mustache template, you can call getVariables() on either the Mailable class or an instance of the MailTemplate model. You can also access the variables property on a MailTemplate instance.

// From the Mailable class
WelcomeMail::getVariables();

// From a MailTemplate instance
$template = MailTemplate::create(['mailable' => WelcomeMail::class, ...]);
$template->getVariables();
// or
$template->variables;

To use database-stored templates, your Mailable class must extend Spatie\MailTemplates\TemplateMailable.

You can define an HTML layout for your templates by implementing the getHtmlLayout() method. This method should return the string content of your layout (e.g., by reading a file from storage).

Example implementation:

namespace App\Mail;

use Spatie\MailTemplates\TemplateMailable;

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

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

The MailTemplate model provides static and scope methods to find templates associated with a specific Laravel Mailable class. This is useful when you want to automatically fetch the database record that matches the mailable you are currently sending.

• MailTemplate::findForMailable($mailable): Returns the first MailTemplate where the mailable column matches the class name of the provided $mailable. Throws a MissingMailTemplate exception if no template is found.
• MailTemplate::forMailable($mailable): A query scope that allows you to further chain Eloquent queries when looking for templates for a specific mailable class.

// Find the template for a specific mailable instance
$template = MailTemplate::findForMailable($myMailable);

// Or use the scope to build a query
$templates = MailTemplate::forMailable($myMailable)->where('active', true)->get();

The MailTemplate model exposes several methods to retrieve the data required to render an email. These methods access the underlying database columns:

• getSubject(): Returns the email subject string.
• getHtmlTemplate(): Returns the HTML body content.
• getTextTemplate(): Returns the plain text body content (nullable).
• getHtmlLayout(): Returns an optional HTML layout string (defaults to null).
• getTextLayout(): Returns an optional plain text layout string (defaults to null).
• getVariables(): Returns an array of variables required by the mailable. This method attempts to call getVariables() on the mailable class specified in the mailable column.

$template = MailTemplate::first();

$subject = $template->getSubject();
$html = $template->getHtmlTemplate();
$variables = $template->getVariables(); // Also accessible via $template->variables