Mjml Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   npm install -g mjml  # Install MJML CLI globally via Node.js
   composer require assoconnect/mjml-bundle
   

2. Configure the Bundle: Add to config/bundles.php:

   Assoconnect\MJMLBundle\AssoconnectMJMLBundle::class => ['all' => true],
   

3. Create an MJML Template: Save a file like templates/emails/welcome.mjml.twig:

   <mjml>
       <mj-body>
           <mj-section>
               <mj-column>
                   <mj-text>Hello {{ name }}!</mj-text>
               </mj-column>
           </mj-section>
       </mj-body>
   </mjml>
   

4. Trigger Cache Warmup:

   php bin/console cache:warmup --env=prod
   

   This compiles MJML to HTML and stores it in var/cache/prod/.

5. Use in Twig:

   {% render 'emails/welcome.html.twig', { name: 'John' } %}
   

First Use Case: Dynamic Email Templates

• Goal: Send personalized emails with MJML templates.
• Steps:
  1. Create templates/emails/newsletter.mjml.twig with dynamic content.
  2. Warm the cache to pre-compile MJML.
  3. Render in a controller:

     $html = $this->get('twig')->render('emails/newsletter.html.twig', [
         'user' => $user,
         'products' => $products,
     ]);
     

  4. Send via a service like Symfony Mailer or a third-party API.

Implementation Patterns

Workflow: Template Development

1. Write MJML in Twig: Use .mjml.twig files for MJML syntax with embedded Twig logic. Example:

   <mjml>
       <mj-section background-color="{{ bg_color }}">
           <mj-column>
               <mj-text font-size="20px">{{ headline }}</mj-text>
           </mj-column>
       </mj-section>
   </mjml>
   

2. Cache Warmup: Run cache:warmup to compile MJML to HTML. The bundle generates .html.twig files in var/cache/.

3. Reuse Compiled Templates: Render the compiled .html.twig files with dynamic data:

   {% render 'emails/compiled/newsletter.html.twig', {
       headline: 'Summer Sale!',
       bg_color: '#FF5733'
   } %}
   

Integration Tips

• Custom Tags: Define reusable MJML components in Twig includes (e.g., templates/_components/header.mjml.twig) and include them:

  {% include '_components/header.mjml.twig' %}
  

• Environment-Specific Config: Override MJML CLI path in config/packages/assoconnect_mjml.yaml:

  assoconnect_mjml:
      mjml_binary: '/usr/local/bin/mjml-custom'
  

• Debugging Compilation: Use --verbose flag in cache:warmup to inspect MJML compilation logs.

• CI/CD Pipeline: Add cache warming to deployment scripts to ensure templates are pre-compiled.

Gotchas and Tips

Pitfalls

1. Deprecated Bundle:

   • This package is archived and no longer maintained. Use alternatives like:
     • spatie/laravel-mjml (Laravel).
     • Direct MJML CLI integration with Symfony’s Process component.

2. Cache Invalidation:

   • Manually clear cache (cache:clear) if MJML templates are updated but changes aren’t reflected.
   • Avoid editing .html.twig files directly in var/cache/—they are auto-generated.

3. MJML CLI Dependency:

   • Ensure Node.js and MJML CLI (mjml) are installed globally. Test with:

     mjml --version
     

4. Twig Expressions in MJML:

   • Twig logic (e.g., {{ if }}, {% for %}) won’t resolve during compilation. Only use static values or variables passed at render time:

     <!-- ❌ Won't work (Twig logic) -->
     {% if promo %}
         <mj-text>Promo!</mj-text>
     {% endif %}
     
     <!-- ✅ Works (static or render-time value) -->
     <mj-text>{{ promo_message }}</mj-text>
     

5. File Naming:

   • Templates must follow the pattern *.mjml.twig. The bundle ignores other extensions.

Debugging

1. Compilation Errors:

   • Check var/log/dev.log for MJML CLI output. Errors may appear as Symfony exceptions.

2. Missing Templates:

   • Ensure the template path is correct (e.g., templates/emails/) and the file exists. The bundle throws a CommandNotFoundException if the template is missing.

3. Performance:

   • Compilation is slow. Pre-warm cache in staging/production to avoid runtime delays.

Extension Points

1. Custom MJML CLI Arguments: Override default MJML CLI flags in config:

   assoconnect_mjml:
       mjml_args: ['--minify', '--no-hide-attributes']
   

2. Post-Compilation Processing: Extend the bundle by listening to the mjml.compile event (if supported) to modify compiled HTML.

3. Alternative Storage: Change cache directory in config/packages/assoconnect_mjml.yaml:

   assoconnect_mjml:
       cache_dir: '%kernel.project_dir%/var/mjml_cache'