README

Build responsive e-mails easily using MJML and Laravel Mailables.

MJML

MJML is a markup language, from MailJet, that reduces the effort required to develop responsive emails. For more information, have a look at the documentary.

Installation

To install this package, run this composer command:

composer require dayLaborers/laravel-mjml

After composer installs the packages, you can publish the package configuration using artisan command:

php artisan vendor:publish --tag=mjml-config

Configuration

There are two options, to render MJML:

cli: Use the MJML npm package
api: Use the public MJML API

The desired procedure can be configured via the environment variable MJML_PROCEDURE. Default is api.

API procedure

To render MJML via the API, you must set the following environment variables:

MJML_PROCEDURE=api
MJML_APP_ID=your-application-id
MJML_SECRET_KEY=your-secret-key

You can also omit MJML_PROCEDURE, as the default value is api. The API credentials can request here

CLI procedure

If you prefer not to render MJML via the API, you can use the NPM package. You must install this in advance and set the following enviroment variables:

MJML_PROCEDURE=cli
MJML_CLI_PATH=path_to_your_mjml_package

MJML_CLI_PATH has the default value node_modules/.bin/mjml, you only need to set this variable if the path to your MJML package differs.

Example

Now you can use MJML for your Laravel Mails. For example, you can use MJML to verify the email after registration. To use Email Verification in your Laravel App, see the documentation here.

Add an MJML Template to your ressource path:

resources\views\emails\notifications\verify.mjml.blade.php

The Template File must have the mjml.blade.php extension.

<mjml>
    <mj-body>
        <mj-section>
            <mj-column>
                <mj-text font-size="20px" color="#F45E43">{{ $verificationUrl }}</mj-text>
            </mj-column>
        </mj-section>
    </mj-body>
</mjml>

If you want to use Blade directives, you must wrapped this in mj-raw tags:

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

Create a Mailable

To create a Mailable use the artisan command: php artisan make:mail VerifyEmail

Customize the class

In your Mailable class generated by laravel, you must now adjust the following:

use DayLaborers\LaravelMjml\Mail\MjmlMailable;

class VerifyEmail extends MjmlMailable
{
    /**
     * @param string $verificationUrl
     */
    public function __construct(protected string $verificationUrl)
    {
        //
    }
    
    /**
     * @return Content
     */
    public function content(): Content
    {
        return new Content(
            view: 'emails.notifications.verify',
            with: [
                'verificationUrl' => $this->verificationUrl
            ]
        );
    }
}

Of course, you can pass more variables and customize things as described in the Laravel documentation.

Customize the email verification

Open the AppServiceProvider.php class and add this:

use Illuminate\Auth\Notifications\VerifyEmail;
use Illuminate\Support\ServiceProvider;
use App\Mail\VerifyEmail as MjmlVerifyEmail;

public function boot(): void
{
    // ...
    
    VerifyEmail::toMailUsing(function (object $notifiable, string $url) {
        return (new MjmlVerifyEmail($url))
            ->to($notifiable->email)
            ->subject('Verify Email Address');
    });
}

Now the verification Mail is rendered with MJML.

That's it! You have successfully installed and configured the MJML package for use.

daylaborers / laravel-mjml

Maintainers

Details