README

MJML 是一种标记语言，旨在减轻编写响应式电子邮件的痛苦。我们的 mjml-php 包可以将 MJML 转换为 HTML。

以下是如何使用我们包的示例

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);

返回的 HTML 将看起来像 此快照文件 中的 HTML（太大，无法内联在此说明中）。大多数电子邮件客户端都能完美地渲染此 HTML。

支持我们

我们投入了大量资源来创建 最佳的开源包。您可以通过 购买我们的付费产品之一 来支持我们。

我们非常感谢您从家乡寄来明信片，说明您正在使用我们哪个包。您可以在 我们的联系页面 上找到我们的地址。我们将所有收到的明信片发布在我们的 虚拟明信片墙 上。

安装

您可以通过 composer 安装此包

composer require spatie/mjml-php

在您的项目或服务器上，您必须安装 JavaScript 包 mjml。

npm install mjml

... 或 Yarn。

yarn add mjml

确保您已安装 Node 16 或更高版本。

用法

将 MJML 转换为 HTML 的最简单方法是使用 toHtml() 方法。

use Spatie\Mjml\Mjml;

// let's assume $mjml contains the MJML you want to convert

$html = Mjml::new()->toHtml($mjml);

如果无法完全转换 MJML，则将抛出 Spatie\Mjml\Exceptions\CouldNotRenderMjml 异常。

使用 convert()

toHtml() 方法将仅返回转换后的 HTML。还有一个 convert() 方法，它将返回一个包含转换后的 HTML 和一些元数据的 Spatie\Mjml\MjmlResult 实例。

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

在返回的 Spatie\Mjml\MjmlResult 实例上，您可以调用以下方法

• html()：返回转换后的 HTML
• array()：返回给定 MJML 的结构化版本
• hasErrors()：返回一个布尔值，指示转换 MJML 时是否出现错误
• errors()：返回一个数组，包含在转换 MJML 时发生的错误

errors() 方法返回一个包含 Spatie\Mjml\MjmlError 实例的数组。每个 Spatie\Mjml\MjmlError 都有以下方法

• line()：返回错误发生的行号
• message()：返回错误消息
• formattedMessage()：返回带有前缀的行号的错误消息
• tagName()：返回错误发生的标签名

自定义渲染

您可以在 Mjml 类上调用各种方法来自定义渲染。例如，minify() 方法将压缩返回的 HTML。

use Spatie\Mjml\Mjml;

// let's assume $mjml contains the MJML you want to convert
$minifiedHtml = Mjml::new()->minify()->toHtml($mjml);

这些都是您可以在 Mjml 类上调用的方法

• minify()：压缩返回的 HTML
• beautify()：美化返回的 HTML
• hideComments()：隐藏返回的 HTML 中的注释
• validationLevel(ValidationLevel $validationLevel)：将验证级别设置为strict、soft或skip

您可以选择不使用这些专用方法，而是将带有选项的数组作为toHtml或convert方法的第二个参数传递。您可以使用在MJML 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,
]);

验证 MJML

您可以使用canConvert()方法确保一个片段的 MJML 是有效的。

use Spatie\Mjml\Mjml;

Mjml::new()->canConvert($mjml); // returns a boolean

如果返回true，则可以将给定的 MJML 转换为 HTML。然而，在将 MJML 转换为 HTML 时，仍可能存在一些错误。这些错误不是致命的，MJML 仍将被转换为 HTML。您可以在调用convert时返回的MjmlResult实例上调用errors()来查看这些非致命错误。

您可以使用canConvertWithoutErrors来确保 MJML 不仅是有效的，而且在将其转换为 HTML 时没有非致命错误。

use Spatie\Mjml\Mjml;

Mjml::new()->canConvertWithoutErrors($mjml); // returns a boolean

指定 nodejs 可执行文件路径

默认情况下，该软件包将尝试确定node可执行文件的路径。如果软件包找不到路径，您可以在环境变量MJML_NODE_PATH中指定一个路径。

MJML_NODE_PATH=/home/user/.nvm/versions/node/v20.11.0/bin

副车

此软件包还支持在 Laravel 项目中通过Sidecar运行。

要使用->sidecar()方法，需要几个额外步骤

安装 Sidecar 软件包

composer require spatie/mjml-sidecar

在您的sidecar.php配置文件中注册MjmlFunction。

/*
 * All of your function classes that you'd like to deploy go here.
 */
'functions' => [
    \Spatie\MjmlSidecar\MjmlFunction::class,
],

通过运行来部署 Lambda 函数

php artisan sidecar:deploy --activate

有关详细信息，请参阅Sidecar 文档。

测试

composer test

变更日志

有关最近更改的更多信息，请参阅变更日志。

贡献

有关详细信息，请参阅贡献指南。

安全漏洞

有关如何报告安全漏洞的详细信息，请参阅我们的安全策略。

鸣谢

• Freek Van der Herten
• 所有贡献者

许可证

MIT 许可证 (MIT)。有关更多信息，请参阅许可证文件。