Cssinliner Extra Laravel Package

Getting Started

Minimal Steps

1. Install the Package

   composer require twig/cssinliner-extra
   

2. Register the Extension In Laravel, add the extension to your Twig environment in config/view.php:

   'extensions' => [
       Twig\Extra\CssInliner\CssInlinerExtension::class,
   ],
   

3. First Use Case Inline CSS in a Twig template:

   {{ html_content|inline_css }}
   

   Replace html_content with a variable containing HTML and external CSS references.

Implementation Patterns

Basic Usage

• Inline CSS in Twig Templates

  {# Inline all CSS in a section #}
  {{ section_content|inline_css }}
  

• Conditional Inlining

  {% if app.environment === 'production' %}
      {{ page_html|inline_css }}
  {% else %}
      {{ page_html }}
  {% endif %}
  

Integration with Laravel

• Blade Integration Use a custom Blade directive or register the Twig extension in AppServiceProvider:

  public function boot()
  {
      $twig = $this->app['view']->getEngine()->getCompiler();
      $twig->addExtension(new \Twig\Extra\CssInliner\CssInlinerExtension());
  }
  

• Dynamic Content Handling For dynamic content (e.g., CMS pages), inline CSS only for static parts:

  {{ static_part|inline_css }}
  {{ dynamic_part }}
  

Advanced Patterns

• Selective Inlining Use options to control inlining behavior:

  {{ content|inline_css({ exclude: ['.no-inline'] }) }}
  

• Caching Inlined CSS Cache the result to avoid reprocessing:

  $cachedHtml = Cache::remember("css_inlined_{$key}", now()->addHours(1), function() use ($html) {
      return $html|inline_css;
  });
  

• Email Template Optimization Inline CSS for emails to bypass client-side blocking:

  {{ email_body|inline_css }}
  

Gotchas and Tips

Common Pitfalls

1. Performance Impact

   • Inlining CSS increases HTML size and memory usage. Monitor with:

     $memoryBefore = memory_get_usage();
     $inlined = $html|inline_css;
     $memoryAfter = memory_get_usage();
     $memoryUsed = $memoryAfter - $memoryBefore;
     

   • Avoid inlining on large or dynamic content.

2. CSS Conflicts

   • Inlined CSS may override external styles. Test with:

     {{ content|inline_css({ preserve_media_types: true }) }}
     

3. Twig Auto-escaping Ensure content is unescaped if it contains raw HTML:

   {{ raw_html|raw|inline_css }}
   

4. Missing PHP Extensions Ensure the dom extension is enabled:

   php -m | grep dom
   

   If missing, enable it in php.ini:

   extension=dom
   

5. Malformed HTML The package may fail on malformed HTML. Validate input or use a sanitizer like htmlpurifier.

Debugging Tips

• Inspect Inlined Output Use {{ content|inline_css|raw }} to debug the result directly in the browser.

• Log Errors Wrap usage in a try-catch to log issues:

  {% try %}
      {{ content|inline_css }}
  {% catch Exception as e %}
      {{ content }} {# Fallback to original #}
      {# Log error #}
      {{ app('log')->error('CSS inlining failed: ' ~ e.getMessage()) }}
  {% endtry %}
  

• Test with Simple HTML Start with minimal HTML to isolate issues:

  {{ '<div style="color:red">Test</div>'|inline_css }}
  

Configuration Quirks

• Options for inline_css Filter The filter accepts an array of options:

  {{ content|inline_css({
      exclude: ['.skip-me'],
      media: 'print',
      preserve_media_types: true
  }) }}
  

• Laravel Cache Integration Cache inlined results for static content:

  $key = md5($html);
  $inlined = Cache::remember("css_inlined_{$key}", now()->addHours(24), function() use ($html) {
      return $html|inline_css;
  });
  

Extension Points

• Customize Inlining Logic Override the CssInlinerExtension class to add custom behavior:

  class CustomCssInlinerExtension extends \Twig\Extra\CssInliner\CssInlinerExtension
  {
      public function getFilters()
      {
          return [
              new \Twig\TwigFilter('custom_inline_css', [$this, 'customInline']),
          ];
      }
  
      public function customInline($html, array $options = [])
      {
          // Custom logic here
          return parent::inline($html, $options);
      }
  }
  

• Preprocess HTML Clean or preprocess HTML before inlining:

  {{ content|clean_html|inline_css }}