如何解决响应式邮件模板开发效率低下的问题，使用qferr/mjml-twig助你轻松构建专业邮件！-composer-PHP中文网

如何解决响应式邮件模板开发效率低下的问题，使用qferr/mjml-twig助你轻松构建专业邮件！

霞舞

发布： 2025-10-24 10:39:52

原创

655人浏览过

如何解决响应式邮件模板开发效率低下的问题，使用qferr/mjml-twig助你轻松构建专业邮件！

可以通过一下地址学习composer：学习地址

邮件模板开发的痛点：一场与兼容性的持久战

相信很多PHP开发者都曾被响应式邮件模板的开发折磨过。不同邮件客户端（Outlook、Gmail、Apple Mail等）对HTML和CSS的解析标准千差万别，导致我们不得不编写大量冗余的表格布局、内联样式和条件注释，以确保邮件在各种设备和客户端上都能正常显示。这不仅耗费了大量时间，还让模板代码变得臃肿不堪，难以维护。每当设计稿有微小改动，都可能意味着一场大规模的兼容性测试和修改。这种低效且痛苦的开发模式，严重拖慢了项目的进度，也让开发者苦不堪言。

面对这样的困境，业界诞生了像 MJML (Mailjet Markup Language) 这样的解决方案。MJML 提供了一套语义化的组件，让我们能够以更简洁、更直观的方式构建响应式邮件，然后它会负责将其编译成兼容性极佳的HTML代码。MJML本身是一个Node.js库，那么，如何在我们的PHP应用中优雅地使用它，特别是当我们的模板引擎是Twig时呢？

邂逅 `qferr/mjml-twig`：将MJML引入Twig世界

幸运的是，我们有 qferr/mjml-twig 这个Composer包。它是一个Twig扩展，专门用于解决PHP应用中MJML的集成问题。通过它，我们可以在Twig模板中直接编写MJML代码，然后利用一个简单的Twig过滤器，就能将这些MJML编译成最终的响应式HTML。这彻底改变了我们开发邮件模板的方式，让MJML的强大功能与Twig的灵活性完美结合。

qferr/mjml-twig 的核心功能在于提供了一个 mjml_to_html 过滤器。这个过滤器能够识别Twig模板中 {% apply mjml_to_html %} 和 {% endapply %} 之间的MJML内容，并将其发送给MJML渲染器进行编译，最终返回标准的响应式HTML。这意味着你不再需要手动调用MJML编译器，也不必担心数据传递的问题，一切都在Twig的渲染流程中自然发生。

安装与配置：一步到位

使用Composer安装 qferr/mjml-twig 非常简单：

<code class="bash">composer require qferr/mjml-twig</code>

登录后复制

安装完成后，我们需要配置一个MJML渲染器。qferr/mjml-twig 提供了两种渲染方式，以适应不同的项目需求：

BinaryRenderer（二进制渲染器）：这种方式依赖于本地安装的MJML二进制文件。如果你已经安装了Node.js，并且通过npm全局安装了MJML（npm install -g mjml），那么这是最直接的选择。你需要向 BinaryRenderer 提供MJML二进制文件的路径。
- 优点：无需外部API调用，本地编译速度快。
- 缺点：需要本地Node.js环境和MJML安装。
ApiRenderer（API渲染器）：如果你不想在服务器上安装Node.js环境，或者希望利用云服务进行MJML编译，那么可以使用API渲染器。它通过调用MJML官方提供的API来完成编译工作。你需要提供API的 app-id 和 secret-key。
- 优点：无需本地环境，部署更简单。
- 缺点：依赖外部服务，可能产生费用，且有网络延迟。

以下是一个基本的PHP代码示例，展示如何初始化Twig环境并添加 MjmlExtension：

<pre class="brush:php;toolbar:false;"><?php
require_once 'vendor/autoload.php';

use \Qferrer\Mjml\Renderer\ApiRenderer;
use \Qferrer\Mjml\Renderer\BinaryRenderer;
use \Qferrer\Mjml\Twig\MjmlExtension;

// 1. 初始化Twig加载器和环境
$loader = new \Twig\Loader\FilesystemLoader(__DIR__ . '/templates');
$twig = new \Twig\Environment($loader);

// 2. 选择并配置渲染器
// 方式一：使用本地二进制渲染器 (推荐，如果环境允许)
// 假设你的MJML二进制文件在项目的node_modules/.bin/mjml
$renderer = new BinaryRenderer(__DIR__ . '/node_modules/.bin/mjml');

// 方式二：使用MJML API渲染器 (需要注册MJML API获取凭证)
// $api = new \Qferrer\Mjml\Http\CurlApi('YOUR_MJML_APP_ID','YOUR_MJML_SECRET_KEY');
// $renderer = new \Qferrer\Mjml\Renderer\ApiRenderer($api);

// 3. 将MjmlExtension添加到Twig环境
$twig->addExtension(new MjmlExtension($renderer));

// 4. 渲染你的MJML Twig模板
$html = $twig->render('newsletter.mjml.twig', [
    'username' => 'Quentin'
]);

echo $html;

登录后复制

实战演练：在Twig中使用 `mjml_to_html` 过滤器

配置完成后，你就可以在任何Twig模板中愉快地编写MJML了。mjml_to_html 过滤器允许你将整个MJML结构包裹起来，Twig变量也能在MJML中无缝使用。

AI建筑知识问答

用人工智能ChatGPT帮你解答所有建筑问题

查看详情

例如，创建一个 templates/newsletter.mjml.twig 文件：

<pre class="brush:php;toolbar:false;">{# templates/newsletter.mjml.twig #}
{% apply mjml_to_html %}
<mjml>
    <mj-body>
        <mj-section>
            <mj-column>
                <mj-text>
                    Hello {{ username }}!
                    <p>This is a responsive email built with MJML and Twig.</p>
                    <mj-button href="https://example.com">Visit our site</mj-button>
                </mj-text>
            </mj-column>
        </mj-section>
        <mj-section background-color="#f0f0f0">
            <mj-column>
                <mj-text font-size="12px" color="#666">
                    &copy; 2023 Your Company. All rights reserved.
                </mj-text>
            </mj-column>
        </mj-section>
    </mj-body>
</mjml>
{% endapply %}

登录后复制

当你渲染这个模板时，username 变量会被Twig替换，然后整个MJML内容会被 mjml_to_html 过滤器处理，最终输出的是一段完整的、响应式良好的HTML邮件代码。

如果你在使用Symfony框架，集成会更加自动化。你只需在 config/services.yaml 中注册 MjmlExtension 并将其标记为 twig.extension，框架就会自动为你处理：

<pre class="brush:php;toolbar:false;"># config/services.yaml
services:
  # Qferrer\Mjml\Http\CurlApi:
  #  arguments:
  #     - '%env(MJML_APP_ID)%' # 从环境变量获取API ID
  #     - '%env(MJML_SECRET_KEY)%' # 从环境变量获取Secret Key

  # mjml_renderer:
  #  class: Qferrer\Mjml\Renderer\ApiRenderer
  #  arguments:
  #    - '@Qferrer\Mjml\Http\CurlApi' # 注入API服务

  mjml_renderer:
    class: Qferrer\Mjml\Renderer\BinaryRenderer
    arguments:
      - '%kernel.project_dir%/node_modules/.bin/mjml' # MJML二进制路径

  Qferrer\Mjml\Twig\MjmlExtension:
    arguments: ['@mjml_renderer']
    tags: ['twig.extension']

登录后复制