Defective Code Logo

Total Downloads Latest Stable Version Latest Stable Version

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

升级

如果您是从以前的版本升级，请参阅升级指南以获取破坏性更改和迁移步骤。

介绍

MJML 是一种专门设计的标记语言，旨在简化响应式电子邮件编码的过程。它的语义语法确保了易用性和简洁性，同时其丰富的标准组件库加速了开发并减少了电子邮件代码库的复杂性。MJML 的开源引擎生成高质量、响应式的 HTML，遵循最佳实践。如果您在使用 Outlook 时感到沮丧，那么这个包就是为您量身定制的。

我们的 MJML 实现作为官方 MJML API 的包装器。它允许在 PHP 中方便地将 MJML 编译为 HTML，无需 NodeJS。这个包非常适合希望在不麻烦安装 NodeJS 和 MJML CLI 的情况下集成 MJML 的 PHP 应用程序。

示例

// 没有 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"]
    }

    在 composer 的安装或更新过程中，MJML 二进制文件将从我们的 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 包相同的配置，除了以下几项：

字体

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

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

注释

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

您还可以通过调用 keepComments() 方法恢复 removeComments() 的效果。

忽略包含

默认情况下，我们的包会忽略 mj-include 标签。这与 MJML 5 的更安全默认值相匹配。您可以通过调用 ignoreIncludes(false) 启用包含。

启用包含时，使用 filePath(string $path) 作为基础目录，使用 includePath(string|array|null $path) 来允许额外的包含目录。

美化

我们的包将使用 js-beautify 美化 HTML。MJML 5.2 也在内部使用 js-beautify，但此包保留包装级别的美化，以便自定义 PHP beautifyOptions 继续生效。默认选项为：

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

您可以通过提供有效的 js-beautify 配置使用以下方法重写这些选项：

缩小

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

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

为什么要基于 PHP 的缩小？ MJML 5 不再使用旧的脆弱的 html-minifier 包。该包仍然在 PHP 中保留缩小处理，以保持在 2.x 版本中引入的输出行为。如果您需要 MJML 5 的本地 htmlnano/cssnano 缩小选项，请打开一个问题，附上所需的选项形状。

验证级别

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

文件路径

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

MJML 5 将 filePath 视为包含的沙箱基础。如果启用了包含，filePath 之外的路径将被拒绝，除非通过 includePath(string|array|null $path) 明确允许。

Juice

我们默认不提供任何 juice 选项。您可以使用以下方法添加 juice 选项：

支持指南

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

社区驱动支持

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

错误和功能优先级

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

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

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

2. 社区拉取请求

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

3. 财务支持

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

社区贡献

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

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

许可 - MIT 许可

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

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

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

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