README

Laravel MJML lets you write responsive HTML emails with MJML directly inside your Blade templates. Any view named *.mjml.blade.php is first compiled by the Blade engine and then converted to production-ready, email-client-safe HTML, so you keep the full power of Blade (components, slots, directives, localization) while authoring with MJML's concise, responsive syntax.

The package registers a dedicated mjml view engine, ships a set of ready-to-use Blade email components and a notification-friendly MailMessage, and supports three conversion backends out of the box: a local Node renderer (default), the hosted MJML API, or your own custom action.

Installation

You can install the package via composer:

composer require maize-tech/laravel-mjml

You can publish the config file and the views with the install command:

php artisan laravel-mjml:install

This is the contents of the published config file:

use Maize\Mjml\Actions\APIConvert;
use Maize\Mjml\Actions\NodeConvert;
use Maize\Mjml\ConversionMode;

return [

    /*
    |--------------------------------------------------------------------------
    | Conversion mode
    |--------------------------------------------------------------------------
    |
    | Here you may specify the conversion mode you may wish to use.
    | Available options are:
    | - Maize\Mjml\ConversionMode::Node
    | - Maize\Mjml\ConversionMode::API
    | - Maize\Mjml\ConversionMode::Custom
    |
    | By default, the value is Maize\Mjml\ConversionMode::Node
    |
    */

    'mode' => ConversionMode::Node,

    'node' => [

        /*
        |--------------------------------------------------------------------------
        | Conversion action
        |--------------------------------------------------------------------------
        |
        | Here you may specify the fully qualified class name of the conversion action.
        | By default, the value is Maize\Mjml\Actions\ConvertMjml::class
        |
        */

        'action' => NodeConvert::class,

        /*
        |--------------------------------------------------------------------------
        | Node options
        |--------------------------------------------------------------------------
        |
        | Here you may specify the options to use when converting MJML to HTML.
        | See available options at https://github.com/mjmlio/mjml#inside-nodejs
        |
        */

        'options' => [
            'keepComments' => true,
            'ignoreIncludes' => false,
            'beautify' => false,
            'minify' => false,
        ],
    ],

    'api' => [

        /*
        |--------------------------------------------------------------------------
        | Conversion action
        |--------------------------------------------------------------------------
        |
        | Here you may specify the fully qualified class name of the conversion action.
        | By default, the value is Maize\Mjml\Actions\ApiConvert::class
        |
        */

        'action' => APIConvert::class,

        /*
        |--------------------------------------------------------------------------
        | API Authentication credentials
        |--------------------------------------------------------------------------
        |
        | Here you may specify the basic auth credentials to use the MJML API.
        |
        */

        'auth_user' => env('MJML_API_AUTH_USER'),
        'auth_password' => env('MJML_API_AUTH_PASSWORD'),
    ],

    'custom' => [

        /*
        |--------------------------------------------------------------------------
        | Conversion action
        |--------------------------------------------------------------------------
        |
        | Here you may specify the fully qualified class name of the conversion action.
        |
        */

        'action' => null,

    ],

];

Usage

Conversion modes

The mode config option determines how MJML markup is turned into HTML.

ConversionMode::Node (the default) renders MJML locally through spatie/mjml-php, which relies on the mjml Node binary:

npm install -g mjml

ConversionMode::API sends the MJML markup to the hosted MJML API and requires the following environment variables:

MJML_API_AUTH_USER=your-application-id
MJML_API_AUTH_PASSWORD=your-secret-key

ConversionMode::Custom lets you provide your own invokable action. It receives the compiled MJML string and must return the rendered HTML:

namespace App\Actions;

class MyConvert
{
    public function __invoke(string $value): string
    {
        // convert $value (MJML) into HTML and return it
    }
}

// config/mjml.php
'mode' => ConversionMode::Custom,

'custom' => [
    'action' => \App\Actions\MyConvert::class,
],

Notifications

Use the package's MailMessage inside a notification's toMail method to render the notification with MJML instead of the default Laravel mail template. It extends Laravel's MailMessage, so the familiar fluent API (greeting, line, action, salutation, ...) keeps working:

use Illuminate\Notifications\Notification;
use Maize\Mjml\MailMessage;

class OrderShipped extends Notification
{
    public function via(object $notifiable): array
    {
        return ['mail'];
    }

    public function toMail(object $notifiable): MailMessage
    {
        return (new MailMessage)
            ->subject('Your order has shipped')
            ->greeting('Hello!')
            ->line('Your order is on its way.')
            ->action('Track your order', url('/orders/123'))
            ->line('Thank you for shopping with us!');
    }
}

Custom MJML views

Any view whose name ends with .mjml.blade.php is automatically compiled by Blade and converted to HTML. You can use it like any other Blade view — for example as a mailable view:

{{-- resources/views/emails/welcome.mjml.blade.php --}}
<mjml>
    <mj-body>
        <mj-section>
            <mj-column>
                <mj-text>Welcome, {{ $name }}!</mj-text>
            </mj-column>
        </mj-section>
    </mj-body>
</mjml>

use Illuminate\Mail\Mailable;

class WelcomeMail extends Mailable
{
    public function __construct(public string $name)
    {
    }

    public function build(): self
    {
        return $this->view('emails.welcome', [
            'name' => $this->name,
        ]);
    }
}

Blade components

When you publish the views, a set of x-mjml::* Blade components becomes available to help you build consistent, well-styled emails:

Example:

<x-mjml::layout>
    <x-mjml::line>
        # Hello!

        Thanks for joining us.
    </x-mjml::line>

    <x-mjml::button url="https://example.com" color="#48bb78">
        Get started
    </x-mjml::button>
</x-mjml::layout>

Testing

composer test

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

• Riccardo Dalla Via
• Enrico De Lazzari
• All Contributors

License

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