Mjml Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require spatie/mjml-php
   

   No additional configuration is required—just autoload the package.

2. First Use Case: Convert a simple MJML template to HTML:

   use Spatie\Mjml\Mjml;
   
   $mjml = <<<'MJML'
   <mjml>
     <mj-body>
       <mj-section>
         <mj-column>
           <mj-text>Hello, World!</mj-text>
         </mj-column>
       </mj-section>
     </mj-body>
   </mjml>
   MJML;
   
   $html = Mjml::new()->toHtml($mjml);
   

   Output: Renders a responsive email-ready HTML block.

3. Where to Look First:

   • README for basic usage.
   • Tests for edge cases and examples.
   • MJML Docs for markup reference.

Implementation Patterns

Core Workflow

1. Template Storage:

   • Store MJML templates in Blade files (e.g., resources/views/emails/welcome.mjml) or as strings.
   • Example Blade template:

     <mjml>
       <mj-body>
         <mj-section>
           <mj-column>
             <mj-text>{{ $greeting }}</mj-text>
           </mj-column>
         </mj-section>
       </mj-body>
     </mjml>
     

2. Conversion in Controllers/Jobs:

   use Spatie\Mjml\Mjml;
   use Illuminate\Support\Facades\View;
   
   $mjml = View::file('emails.welcome', ['greeting' => 'Hi there!']);
   $html = Mjml::new()->toHtml($mjml);
   

3. Integration with Mailables: Extend Laravel’s Mailable class to use MJML:

   use Spatie\Mjml\Mjml;
   use Illuminate\Mail\Mailable;
   
   class WelcomeMailable extends Mailable
   {
       public function build()
       {
           $mjml = $this->view('emails.welcome');
           $html = Mjml::new()->toHtml($mjml);
   
           return $this->subject('Welcome!')
                       ->html($html);
       }
   }
   

4. Dynamic Content: Use MJML’s built-in components (e.g., <mj-button>, <mj-image>) for interactive elements:

   <mj-button href="{{ $url }}" background-color="#000000">
     Click Me
   </mj-button>
   

5. Caching: Cache converted HTML to avoid reprocessing:

   $html = Cache::remember("mjml_{$template}", now()->addHours(1), function () {
       return Mjml::new()->toHtml($mjml);
   });
   

Gotchas and Tips

Pitfalls

1. Invalid MJML:

   • The package validates MJML syntax. Invalid markup (e.g., unclosed tags) throws exceptions.
   • Fix: Use MJML Playground to validate templates before integration.

2. Email Client Quirks:

   • Some clients (e.g., Gmail) strip styles. Use inline CSS or tools like Premailer post-conversion:

     use Spatie\Mjml\Mjml;
     use Premailer\Premailer;
     
     $html = Mjml::new()->toHtml($mjml);
     $premailer = new Premailer();
     $html = $premailer->transform($html);
     

3. Performance:

   • Large MJML templates may slow down conversion. Test with production-sized templates.

4. Attribute Handling:

   • MJML attributes (e.g., padding, background-color) must match MJML spec. Invalid attributes are ignored silently.

Debugging Tips

1. Enable Verbose Output: Use Mjml::new()->debug(true) to log conversion steps (helpful for troubleshooting).

2. Compare Snapshots: For complex templates, compare output against MJML’s live preview or the package’s snapshot tests.

3. Check for Deprecated Tags: The package supports MJML v4+. If using older MJML, update tags (e.g., <mj-section> instead of <mjml-section>).

Extension Points

1. Custom Components: Extend the package by creating a wrapper for reusable MJML snippets:

   class EmailComponent
   {
       public static function header(string $title): string
       {
           return <<<MJML
           <mj-section>
             <mj-column>
               <mj-text font-size="24px" color="#333">{$title}</mj-text>
             </mj-column>
           </mj-section>
           MJML;
       }
   }
   

2. Post-Processing: Chain methods to modify HTML after conversion:

   $html = Mjml::new()
               ->toHtml($mjml)
               ->replace('{{url}}', $this->url)
               ->prepend('<div>Footer</div>');
   

3. Configuration: Override default options (e.g., minify output):

   Mjml::new()->minify(true)->toHtml($mjml);
   

Pro Tips

• Use MJML’s CLI: For local development, use mjml --watch to preview changes in real-time.
• Laravel Mix: Process MJML templates during asset compilation:

  // mix.js
  const mjml = require('mjml');
  mix.process('resources/mjml/email.mjml', (content) => {
      return mjml(content).html;
  });
  

• Testing: Use Pest’s snapshot testing to ensure HTML consistency across updates:

  expect($html)->toMatchSnapshot();