spatie / mjml-php
Convert MJML to HTML using PHP
Fund package maintenance!
spatie
Installs: 149 642
Dependents: 6
Suggesters: 0
Security: 0
Stars: 223
Watchers: 6
Forks: 10
Open Issues: 0
Requires
- php: ^8.1
- symfony/process: ^6.3.2|^7.0
Requires (Dev)
- laravel/pint: ^1.11
- pestphp/pest: ^2.16
- spatie/ray: ^1.37.2
Suggests
- spatie/mjml-sidecar: When you want to run MJML compilation through Sidecar in a Laravel project
README
MJML is a markup language designed to reduce the pain of coding a responsive email. Our mjml-php
package can convert MJML to HTML.
Here's an example of how to use our package:
use Spatie\Mjml\Mjml; $mjml = <<<'MJML' <mjml> <mj-body> <mj-section> <mj-column> <mj-text invalid-attribute>Hello World</mj-text> </mj-column> </mj-section> </mj-body> </mjml> MJML; $html = Mjml::new()->toHtml($mjml);
The returned HTML will look like the HTML in this snapshot file (it's a bit too large to inline in this readme). Most email clients will be able to render this HTML perfectly.
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.
Installation
You can install the package via composer:
composer require spatie/mjml-php
In your project, or on your server, you must have the JavaScript package mjml
installed.
npm install mjml
... or Yarn.
yarn add mjml
Make sure you have installed Node 16 or higher.
Usage
The easiest way to convert MJML to HTML is by using the toHtml()
method.
use Spatie\Mjml\Mjml; // let's assume $mjml contains the MJML you want to convert $html = Mjml::new()->toHtml($mjml);
If the MJML could not be converted at all a Spatie\Mjml\Exceptions\CouldNotRenderMjml
exception will be thrown.
Using convert()
The toHtml()
method will just return the converted HTML. There's also a convert()
method that will return an instance of Spatie\Mjml\MjmlResult
that contains the converted HTML and some metadata.
use Spatie\Mjml\Mjml; // let's assume $mjml contains the MJML you want to convert $result = Mjml::new()->convert($mjml); // returns an instance of Spatie\Mjml\MjmlResult
On the returned instance of Spatie\Mjml\MjmlResult
you can call the following methods:
html()
: returns the converted HTMLarray()
: returns a structured version of the given MJMLhasErrors()
: returns a boolean indicating if there were errors while converting the MJMLerrors()
: returns an array of errors that occurred while converting the MJML
The errors()
method returns an array containing instances of Spatie\Mjml\MjmlError
. Each Spatie\Mjml\MjmlError
has the following methods:
line()
: returns the line number where the error occurredmessage()
: returns the error messageformattedMessage()
: returns the error message with the line number prependedtagName()
: returns the name of the tag where the error occurred
Customizing the rendering
There are various methods you can call on the Mjml
class to customize the rendering. For instance the minify()
method will minify the HTML that is returned.
use Spatie\Mjml\Mjml; // let's assume $mjml contains the MJML you want to convert $minifiedHtml = Mjml::new()->minify()->toHtml($mjml);
These are all the methods you can call on the Mjml
class:
minify()
: minify the HTML that is returnedbeautify()
: beautify the HTML that is returnedhideComments()
: hide comments in the HTML that is returnedvalidationLevel(ValidationLevel $validationLevel)
: set the validation level tostrict
,soft
orskip
Instead of using these dedicated methods, you could opt to pass an array with options as the second argument of the toHtml
or convert
method. You can use any of the options that are mentioned in the MJML documentation for Node.js.
use Spatie\Mjml\Mjml; // let's assume $mjml contains the MJML you want to convert $minifiedHtml = Mjml::new()->minify()->toHtml($mjml, [ 'beautify' => true, 'minify' => true, ]);
Validating MJML
You can make sure a piece of MJML is valid by using the canConvert()
method.
use Spatie\Mjml\Mjml; Mjml::new()->canConvert($mjml); // returns a boolean
If true
is returned we'll be able to convert the given MJML to HTML. However, there may still be some errors while converting the MJML to HTML. These errors are not fatal and the MJML will still be converted to HTML. You can see these non-fatal errors when calling errors()
on the MjmlResult
instance that is returned when calling convert
.
You can use canConvertWithoutErrors
to make sure the MJML is both valid and that there are no non-fatal errors while converting it to HTML.
use Spatie\Mjml\Mjml; Mjml::new()->canConvertWithoutErrors($mjml); // returns a boolean
Specifying the path to nodejs executable
By default, the package itself will try to determine the path to the node
executable. If the package can't find a path, you can specify a path in the environment variable MJML_NODE_PATH
MJML_NODE_PATH=/home/user/.nvm/versions/node/v20.11.0/bin
Sidecar
This package also supports running through Sidecar in Laravel projects.
To use the ->sidecar()
method, a few extra steps are needed:
Install the Sidecar package:
composer require spatie/mjml-sidecar
Register the MjmlFunction
in your sidecar.php
config file.
/* * All of your function classes that you'd like to deploy go here. */ 'functions' => [ \Spatie\MjmlSidecar\MjmlFunction::class, ],
Deploy the Lambda function by running:
php artisan sidecar:deploy --activate
See the Sidecar documentation for details.
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
License
The MIT License (MIT). Please see License File for more information.