English | العربية | বাংলা | Bosanski | Deutsch | Español | Français | हिन्दी | Italiano | 日本語 | 한국어 | मराठी | Português | Русский | Kiswahili | தமிழ் | తెలుగు | Türkçe | اردو | Tiếng Việt | 中文

• 升级
• 介绍
  • 示例
• 安装
• 使用（不使用 Laravel）
  • 渲染 MJML
  • 验证 MJML
• 使用（与 Laravel 一起）
  • 渲染 MJML
  • 验证 MJML
  • 配置
• 配置
  • 字体
  • 注释
  • 忽略包含
  • 美化
  • 压缩
  • 验证级别
  • 文件路径
  • Juice
• 支持指南
  • 社区驱动支持
  • 错误和功能优先级
• 许可 - MIT 许可

🔗升级

如果您正在从之前的版本升级，请查看 升级指南 以了解重大变化和迁移步骤。

🔗介绍

MJML 是一种专门设计的标记语言，旨在简化响应式电子邮件编码的过程。 其语义化的语法确保了易用性和简单性，而其丰富的标准组件库加速了开发并减轻了电子邮件代码库的复杂性。MJML 的开源引擎生成高质量、响应式的 HTML，符合最佳实践。如果您曾经历过使用 Outlook 的挫折，这个包正适合您。

我们的 MJML 实现作为官方 MJML API 的封装。它能够在 PHP 中方便地将 MJML 编译为 HTML，无需 NodeJS。这个包非常适合希望在PHP应用中集成 MJML，而不想麻烦安装 NodeJS 和 MJML CLI 的用户。

🔗示例

// 不使用 Laravel
(new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// 压缩的 HTML
(new MJML)->minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// 使用 Laravel
MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);
 
// 使用 Laravel 和压缩的 HTML
MJML::minify()->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

🔗安装

1. 首先将以下内容添加到您的 composer.json 文件中，以指示我们的包在安装时为您的 操作系统拉取正确的二进制文件。运行 install、update 或 dump-autoload 后，将下载二进制文件。

   {
       "post-autoload-dump": ["DefectiveCode\\MJML\\PullBinary::all"]
   }

   MJML 二进制文件将在 composer 安装或更新过程中从我们的 CDN 获取并保存在此包的“bin”文件夹中。确保在本地和生产环境中加载了必要的二进制文件。

   默认情况下，all 将拉取我们支持的所有二进制文件。我们建议将其限制为您需要的操作和架构系统，以节省带宽和安装时间。以下是可用的二进制文件。

   操作系统	架构	Composer 更新后命令
   所有	所有	DefectiveCode\MJML\PullBinary::all
   Darwin (MacOS)	arm64	DefectiveCode\MJML\PullBinary::darwin-arm64
   Darwin (MacOS)	x64	DefectiveCode\MJML\PullBinary::darwin-x64
   Linux (glibc)	arm64	DefectiveCode\MJML\PullBinary::linux-arm64
   Linux (glibc)	x64	DefectiveCode\MJML\PullBinary::linux-x64
   Linux (musl)	arm64	DefectiveCode\MJML\PullBinary::linux-arm64-musl
   Linux (musl)	x64	DefectiveCode\MJML\PullBinary::linux-x64-musl

2. 接下来，通过运行以下 composer 命令安装 PHP 包：

   composer require defectivecode/mjml

3. 就这样！如果使用 Laravel，我们的包将自动使用 Laravel 的包发现功能进行安装。

🔗使用（不使用 Laravel）

如果您正在使用 Laravel，请查看下方使用 Laravel 的示例。

🔗渲染 MJML

要渲染 MJML，只需将您的 MJML 字符串传递给 render 方法：

use DefectiveCode\MJML;
 
$html = (new MJML)->render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

🔗验证 MJML

要验证 MJML，只需将您的 MJML 字符串传递给 isValid 方法：

use DefectiveCode\MJML;
 
$isValid = (new MJML)->isValid(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

🔗使用（与 Laravel 一起）

🔗渲染 MJML

要渲染 MJML，只需将您的 MJML 字符串传递给 MJML facade 的 render：

use DefectiveCode\MJML\Facades\MJML;
 
$html = MJML::render(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

🔗验证 MJML

要验证 MJML，只需将您的 MJML 字符串传递给 MJML facade 的 isValid 方法：

use DefectiveCode\MJML\Facades\MJML;
 
$isValid = MJML::isValid(
    '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
);

🔗配置

您可以使用以下命令发布配置文件：

php artisan vendor:publish --provider="DefectiveCode\MJML\MJMLServiceProvider"

这将在您的 config 文件夹中创建一个 mjml.php 配置文件。配置文件中列出的所有选项将在使用 MJML facade 时传递给 config 对象。

🔗配置

所有配置选项可以通过直接在 MJML 对象上调用以下方法进行设置。

use DefectiveCode\MJML;
 
$html = (new MJML)
    ->setMinify(true)
    ->setBeautify(false)
    ->render(
        '<mjml><mj-body><mj-section><mj-column><mj-text>Hello World</mj-text></mj-column></mj-section></mj-body></mjml>'
    );

我们的包遵循与官方 MJML 包的 相同配置，除了以下几点：

• preprocessors - 此选项不可用。如果您希望添加此选项，请打开一个拉取请求。
• minifyOptions - 我们使用轻量级的基于 PHP 的压缩器，而不是 html-minifier。压缩器会删除注释（除 Outlook 条件外），折叠空格，并删除标签之间的空格。

🔗字体

我们的包默认使用以下字体：

• Open Sans: 'https://fonts.googleapis.com/css?family=Open+Sans:300,400,500,700'
• Droid Sans: 'https://fonts.googleapis.com/css?family=Droid+Sans:300,400,500,700'
• Lato: https://fonts.googleapis.com/css?family=Lato:300,400,500,700
• Roboto: https://fonts.googleapis.com/css?family=Roboto:300,400,500,700
• Ubuntu: https://fonts.googleapis.com/css?family=Ubuntu:300,400,500,700

您可以通过使用以下方法更改字体：

• addFont(string $font, string $url) - 将字体添加到字体列表中。
• removeFont(string $font) - 从字体列表中删除字体。
• setFonts(array $fonts) - 设置字体列表。您应该提供以下格式的字体数组：['font-name' => 'font-url']。

🔗注释

默认情况下会保留注释。如果您希望删除注释，可以使用 removeComments() 方法。

您也可以通过调用 keepComments() 方法来恢复 removeComments()。

🔗忽略包含

默认情况下，我们的包会包含任何 mj-include 标签。您可以通过调用 ignoreIncludes(bool $ignore) 方法调整此行为。

🔗美化

我们的包将使用 js-beautify 美化 HTML，默认选项如下：

• indentSize: 2
• wrapAttributesIndentSize: 2
• maxPreserveNewline: 0
• preserveNewlines: false

虽然 js-beautify 使用 snake_case 提供选项，但在使用我们的包时，您应使用 camelCase。我们做出这个选择是为了使我们的包在其余配置选项中保持一致。我们的包将在内部自动将 camelCase 选项转换为 snake_case。

您可以通过提供有效的 js-beautify 配置，以以下方法覆盖这些选项：

• setBeautifyOptions(array $options) - 设置 js-beautify 选项。
• addBeautifyOption(string $option, mixed $value) - 添加 js-beautify 选项。
• removeBeautifyOption(string $option) - 删除 js-beautify 选项。

🔗压缩

当启用时，我们的包将压缩 HTML 输出。压缩会执行以下操作：

• 删除 HTML 注释（保留 Outlook 条件注释，如 <!--[if mso]>）
• 将多个空格字符折叠为单个空格
• 删除 HTML 标签之间的空格

您可以通过调用 minify(bool $minify) 方法启用或禁用压缩。

为什么选择基于 PHP 的压缩？ 官方 MJML 包使用 html-minifier 进行压缩，该压缩工具存在已知的 ReDoS 漏洞 (CVE-2022-37620)，且没有可用的修复，因为该包不再维护。为了避免捆绑有漏洞的依赖项，我们将压缩功能转移到使用轻量级、安全的实现的 PHP 中进行。

🔗验证级别

我们的包默认将使用 soft 验证级别验证 MJML。您可以通过使用 validationLevel(ValidationLevel $validationLevel) 方法更改此设置。以下是可用的验证级别：

• strict - 如果文档有任何错误，则不会进行渲染。
• soft - 即使文档有错误，仍会进行渲染。
• skip - 文档将在不进行验证的情况下渲染。

🔗文件路径

我们的包默认将使用 . 目录。您可以通过调用 filePath(string $path) 方法更改此设置。

🔗Juice

默认情况下，我们不提供任何 juice 选项。您可以通过以下方法添加 juice 选项：

• setJuiceOptions(array $options) - 设置 juice 选项。
• addJuiceOption(string $option, mixed $value) - 添加 juice 选项。
• removeJuiceOption(string $option) - 移除 juice 选项。
• setJuicePreserveTags(array $tags) - 设置 juice 保留标签。
• addJuicePreserveTag(string $tag, mixed $value) - 添加 juice 保留标签。
• removeJuicePreserveTag(string $tag) - 移除 juice 保留标签。

🔗支持指南

感谢您选择我们的开源包！请花一点时间查看这些支持指南。它们将帮助您充分利用我们的项目。

🔗社区驱动支持

我们的开源项目得益于我们出色的社区。如果您有问题或需要帮助，StackOverflow 和其他在线资源是您最好的选择。

🔗错误和功能优先级

管理一个开源项目的现实是我们不能立即解决每一个报告的错误或功能请求。我们按以下顺序优先处理问题：

1. 影响我们付费产品的错误

影响我们付费产品的错误将始终是我们的首要任务。在某些情况下，我们可能只会处理直接影响我们的错误。

2. 社区拉取请求

如果您发现了一个错误并且有解决方案，请提交拉取请求。在影响我们产品的问题之后，我们给这些社区驱动的修复分配下一个最高优先级。经过审查和批准后，我们将合并您的解决方案并给予贡献者信用。

3. 财务支持

对于不属于上述类别的问题，您可以选择为其解决提供资金支持。每个开放问题都与一个订单表相关联，您可以在上面提供财务支持。我们根据提供的资金金额优先处理这些问题。

社区贡献

开源的蓬勃发展依赖于社区的积极参与。即使您不是在修复错误，也可以通过代码改进、文档更新、教程或在社区频道帮助他人来贡献。我们非常鼓励大家作为一个社区共同支持开源工作。

重申一下，DefectiveCode 将根据错误对我们付费产品的影响、社区拉取请求以及收到的财务支持来优先处理问题.

🔗许可 - MIT 许可

版权所有 © Defective Code, LLC。保留所有权利

特此免费授权任何获得此软件及相关文档文件（“软件”）副本的人，允许在软件中自由处理，包括不限于使用、复制、修改、合并、发布、分发、再授权和/或销售软件副本的权利，并允许被提供软件的人这样做，前提是满足以下条件：

上述版权声明和本许可声明应包括在软件的所有副本或重要部分中。

软件按“原样”提供，不提供任何种类的保证，明示或暗示，包括但不限于对适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有者均不对因软件或软件的使用或其他交易而引起的任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权或其他方面。