Getting Started

Start by installing the package via Composer:

composer require tijsverkoyen/css-to-inline-styles

The primary use case is inline styling for HTML email templates, where external/<style> rules are stripped by most email clients. The basic workflow is:

use TijsVerkoyen\CssToInlineStyles\CssToInlineStyles;

$cssToInlineStyles = new CssToInlineStyles();

$html = file_get_contents('email-template.html');
$css = file_get_contents('email-styles.css');

echo $cssToInlineStyles->convert($html, $css);

Always ensure your HTML contains a <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> tag in <head> to avoid UTF-8 issues — the newer <meta charset="UTF-8"> is not sufficient.

Implementation Patterns

Laravel Integration: The package is used internally in Laravel’s Markdown mailable transformer (Illuminate\Mail\Markdown). In Laravel, you can rely on Markdown::html()/text() with inline styles automatically handled when using ->withInlineStyles().

Preprocessing Templates: When using blade or Twig templates, generate clean HTML before inlining. Example with Blade:

$html = View::make('emails.welcome', $data)->render();
$css = File::get(resource_path('css/email.css'));
$inlined = $cssToInlineStyles->convert($html, $css);

Caching Styles: Since CSS parsing is expensive, cache compiled CSS selectors if you reuse the same styles across many emails:

$cssToInlineStyles->setCss($css); // Cache the CSS parser internally
foreach ($recipients as $recipient) {
    $html = View::make('emails.newsletter', $vars)->render();
    $inlined = $cssToInlineStyles->convert($html);
}

Fallback for Email Clients: Combine with Browscap or user-agent sniffing to conditionally inline minimal styles for legacy clients (e.g., Outlook), while keeping others simpler.

Gotchas and Tips

No Pseudo-Selectors: :hover, :nth-child, ::before are silently ignored — design email templates with inline classes only.
CSS Comments Cause Failures: Any CSS inside  is removed, but CSS inside /* CSS comments */ remains unless malformed. Avoid complex comments in emails.
Style Tag Order Matters: Duplicate rules? Later rules win only within the same specificity. Inline styles always win over CSS rules — but order of appearance in <style> blocks can surprise.
Multibyte Strings: Ensure mbstring.func_overload = 2 is set in php.ini, or handle encoding manually. The package relies on ext-mbstring for safe regex processing.
HTML <style> & <link> Handling: If HTML contains <style> blocks, they are extracted automatically — no need to feed CSS separately. But always test with real-world email clients (Mailchimp’s Email Preview or Litmus recommended).
Debugging Tip: Use ->getProcessedHtml() after convert() in development to inspect the raw DOM before inlining — especially useful when styles vanish unexpectedly.
Performance: For batch sends, reuse the CssToInlineStyles instance and avoid re-parsing CSS for every email — it’s fast, but not free.

Css To Inline Styles Laravel Package

Getting Started

Implementation Patterns

Gotchas and Tips