vercoutere/laravel-mjml

A package that allows you to use MJML templates within your Laravel mailables.

v0.4.0 2024-03-22 22:49 UTC

Requires

• php: ^8.2.0
• guzzlehttp/guzzle: ^7.8
• laravel/framework: ^11.0
• soundasleep/html2text: ^2.1
• symfony/process: ^7.0

Requires (Dev)

• orchestra/testbench: ^9.0
• phpunit/phpunit: ^10.5
• symfony/phpunit-bridge: ^7.0

MIT

• Jonathan Vercoutere

README

Installation

Installing this package is done using Composer:

composer require vercoutere/laravel-mjml

Configuration

Rendering strategies

There are two available strategies to use for rendering MJML using this package:

• local: Uses a local MJML binary.
• api: Uses the publicly available MJML API.

The strategy can be configured using an environment variable.

MJML_STRATEGY=local/api

Local strategy

To use the local strategy you will need to have both NodeJS and MJML installed on your machine. It is recommended to install MJML using the available npm package.

If you're not installing MJML using the npm package, you will also need to configure the path to your MJML installation:

MJML_BINARY_PATH=/path/to/your/mjml/installation

API strategy

When using the API strategy, you will need to configure your application id and secret.

MJML_APP_ID=your-app-id
MJML_SECRET_KEY=your-secret

View caching

The MJML compiler implementation extends Laravel's Blade compiler. This means that view caching behaves the same and can be managed using the view:cache Artisan command and the view.cache config variable.

Usage

To use MJML in your mailables, make sure your mails extend the Vercoutere\LaravelMjml\MjmlMailable class instead of the default Illuminate\Mail\Mailable class.

use Illuminate\Mail\Mailables\Content;
use Vercoutere\LaravelMjml\MjmlMailable;

class MyMail extends MjmlMailable
{
    public function content(): Content
    {
        return new Content(
            view: 'my-template',
        );
    }
}

The template files you want to use in an MJML mailable must have a .mjml.blade.php extension.

Blade directives in MJML templates must be wrapped in mj-raw tags to prevent the MJML engine from trying to parse them.

<mjml>
  <mj-body>
    <mj-section>
      <mj-column>
        <mj-raw>@if (true)</mj-raw>
        <mj-text font-size="20px" color="#F45E43">{{ App::environment() }}</mj-text>
        <mj-raw>@endif</mj-raw>
      </mj-column>
    </mj-section>
  </mj-body>
</mjml>