{"id":13593459,"url":"https://github.com/spatie/mjml-php","last_synced_at":"2025-05-15T04:06:33.863Z","repository":{"id":189728613,"uuid":"681192209","full_name":"spatie/mjml-php","owner":"spatie","description":"Convert MJML to HTML using PHP","archived":false,"fork":false,"pushed_at":"2025-05-12T18:57:53.000Z","size":130,"stargazers_count":243,"open_issues_count":0,"forks_count":14,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-05-12T19:55:17.441Z","etag":null,"topics":["html","mail","mjml","php"],"latest_commit_sha":null,"homepage":"https://freek.dev/2549-convert-mjml-to-html-using-php","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spatie.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"spatie"}},"created_at":"2023-08-21T13:24:00.000Z","updated_at":"2025-05-12T18:57:50.000Z","dependencies_parsed_at":"2023-08-21T14:39:28.067Z","dependency_job_id":"b40c69df-d8c1-46c1-8b83-b11ca4572054","html_url":"https://github.com/spatie/mjml-php","commit_stats":{"total_commits":89,"total_committers":8,"mean_commits":11.125,"dds":0.3707865168539326,"last_synced_commit":"e31e7bed4541abd9a5511bc3936a756b11b48184"},"previous_names":["spatie/mjml-php"],"tags_count":16,"template":false,"template_full_name":"spatie/package-skeleton-php","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fmjml-php","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fmjml-php/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fmjml-php/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spatie%2Fmjml-php/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spatie","download_url":"https://codeload.github.com/spatie/mjml-php/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253814869,"owners_count":21968559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["html","mail","mjml","php"],"created_at":"2024-08-01T16:01:20.498Z","updated_at":"2025-05-15T04:06:28.837Z","avatar_url":"https://github.com/spatie.png","language":"PHP","funding_links":["https://github.com/sponsors/spatie"],"categories":["Tools","PHP"],"sub_categories":[],"readme":"# Convert MJML to HTML using PHP\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/spatie/mjml-php.svg?style=flat-square)](https://packagist.org/packages/spatie/mjml-php)\n[![Tests](https://img.shields.io/github/actions/workflow/status/spatie/mjml-php/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/spatie/mjml-php/actions/workflows/run-tests.yml)\n[![Total Downloads](https://img.shields.io/packagist/dt/spatie/mjml-php.svg?style=flat-square)](https://packagist.org/packages/spatie/mjml-php)\n\n[MJML](https://mjml.io) is a markup language designed to reduce the pain of coding a responsive email. Our `mjml-php` package can convert MJML to HTML.\n\nHere's an example of how to use our package:\n\n```php\nuse Spatie\\Mjml\\Mjml;\n\n$mjml = \u003c\u003c\u003c'MJML'\n    \u003cmjml\u003e\n      \u003cmj-body\u003e\n        \u003cmj-section\u003e\n          \u003cmj-column\u003e\n            \u003cmj-text invalid-attribute\u003eHello World\u003c/mj-text\u003e\n          \u003c/mj-column\u003e\n        \u003c/mj-section\u003e\n      \u003c/mj-body\u003e\n    \u003c/mjml\u003e\n    MJML;\n\n$html = Mjml::new()-\u003etoHtml($mjml);\n```\n\nThe returned HTML will look like the HTML in [this snapshot file](https://github.com/spatie/mjml-php/blob/main/tests/.pest/snapshots/MjmlTest/it_can_render_mjml_without_any_options.snap) (it's a bit too large to inline in this readme). Most email clients will be able to render this HTML perfectly.\n\n## Support us\n\n[\u003cimg src=\"https://github-ads.s3.eu-central-1.amazonaws.com/mjml-php.jpg?t=1\" width=\"419px\" /\u003e](https://spatie.be/github-ad-click/mjml-php)\n\nWe invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).\n\nWe 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](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require spatie/mjml-php\n```\n\nIn your project, or on your server, you must have the JavaScript package [`mjml`](https://github.com/mjmlio/mjml) installed.\n\n```bash\nnpm install mjml\n```\n\n... or Yarn.\n\n```bash\nyarn add mjml\n```\n\nMake sure you have installed Node 16 or higher.\n\n## Usage\n\nThe easiest way to convert MJML to HTML is by using the `toHtml()` method.\n\n```php\nuse Spatie\\Mjml\\Mjml;\n\n// let's assume $mjml contains the MJML you want to convert\n\n$html = Mjml::new()-\u003etoHtml($mjml);\n```\n\nIf the MJML could not be converted at all a `Spatie\\Mjml\\Exceptions\\CouldNotRenderMjml` exception will be thrown.\n\n### Using `convert()`\n\nThe `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.\n\n```php\nuse Spatie\\Mjml\\Mjml;\n\n// let's assume $mjml contains the MJML you want to convert\n\n$result = Mjml::new()-\u003econvert($mjml); // returns an instance of Spatie\\Mjml\\MjmlResult\n```\n\nOn the returned instance of `Spatie\\Mjml\\MjmlResult` you can call the following methods:\n\n- `html()`: returns the converted HTML\n- `array()`: returns a structured version of the given MJML\n- `hasErrors()`: returns a boolean indicating if there were errors while converting the MJML\n- `errors()`: returns an array of errors that occurred while converting the MJML\n\nThe `errors()` method returns an array containing instances of `Spatie\\Mjml\\MjmlError`. Each `Spatie\\Mjml\\MjmlError` has the following methods:\n\n- `line()`: returns the line number where the error occurred\n- `message()`: returns the error message\n- `formattedMessage()`: returns the error message with the line number prepended\n- `tagName()`: returns the name of the tag where the error occurred\n\n### Customizing the rendering\n\nThere 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.\n\n```php\nuse Spatie\\Mjml\\Mjml;\n\n// let's assume $mjml contains the MJML you want to convert\n$minifiedHtml = Mjml::new()-\u003eminify()-\u003etoHtml($mjml);\n```\n\nThese are all the methods you can call on the `Mjml` class:\n\n- `minify()`: minify the HTML that is returned\n- `beautify()`: beautify the HTML that is returned\n- `hideComments()`: hide comments in the HTML that is returned\n- `validationLevel(ValidationLevel $validationLevel)`: set the validation level to `strict`, `soft` or `skip`\n\nInstead 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](https://github.com/mjmlio/mjml#inside-nodejs).\n\n```php\nuse Spatie\\Mjml\\Mjml;\n\n// let's assume $mjml contains the MJML you want to convert\n$minifiedHtml = Mjml::new()-\u003eminify()-\u003etoHtml($mjml, [\n    'beautify' =\u003e true,\n    'minify' =\u003e true,\n]);\n```\n\n### Validating MJML\n\nYou can make sure a piece of MJML is valid by using the `canConvert()` method.\n\n```php\nuse Spatie\\Mjml\\Mjml;\n\nMjml::new()-\u003ecanConvert($mjml); // returns a boolean\n```\n\nIf `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`.\n\nYou can use `canConvertWithoutErrors` to make sure the MJML is both valid and that there are no non-fatal errors while converting it to HTML.\n\n```php\nuse Spatie\\Mjml\\Mjml;\n\nMjml::new()-\u003ecanConvertWithoutErrors($mjml); // returns a boolean\n```\n\n### Specifying the path to nodejs executable\n\nBy 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` \n\n```shell\nMJML_NODE_PATH=/home/user/.nvm/versions/node/v20.11.0/bin\n```\n\n## Sidecar\n\nThis package also supports running through [Sidecar](https://github.com/hammerstonedev/sidecar) in Laravel projects.\n\nTo use the `-\u003esidecar()` method, a few extra steps are needed:\n\nInstall the Sidecar package:\n\n```shell\ncomposer require spatie/mjml-sidecar\n```\n\nRegister the `MjmlFunction` in your `sidecar.php` config file.\n\n```php\n/*\n * All of your function classes that you'd like to deploy go here.\n */\n'functions' =\u003e [\n    \\Spatie\\MjmlSidecar\\MjmlFunction::class,\n],\n```\n\nDeploy the Lambda function by running:\n\n```shell\nphp artisan sidecar:deploy --activate\n```\n\nSee the [Sidecar documentation](https://hammerstone.dev/sidecar/docs/main/functions/deploying) for details.\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](../../security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Freek Van der Herten](https://github.com/freekmurze)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Fmjml-php","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspatie%2Fmjml-php","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspatie%2Fmjml-php/lists"}