Getting Started

Minimal Steps

Installation:
```
composer require pelago/emogrifier
```
Add to composer.json under require if preferred.

Basic Inlining: For HTML emails or mobile-optimized content, inline CSS directly:

use Pelago\Emogrifier\CssInliner;

$html = '<html><body><p class="email-text">Hello</p></body></html>';
$css = '.email-text { color: red; }';

$inlinedHtml = CssInliner::fromHtml($html)->inlineCss($css)->render();

Output: <p style="color: red;">Hello</p> (with proper HTML structure preserved).

No External CSS? Skip the $css parameter to parse <style> blocks in the HTML:
```
$inlinedHtml = CssInliner::fromHtml($html)->inlineCss()->render();
```
First Use Case:
- Email Templates: Convert styled HTML emails to inline CSS for compatibility with Outlook/Gmail.
- Legacy Systems: Ensure CSS works on devices/browsers with limited support (e.g., older mobile browsers).

Implementation Patterns

Core Workflow

Preprocessing: Normalize HTML structure (add missing <head>, <body>, fix nesting):

use Pelago\Emogrifier\HtmlProcessor\HtmlNormalizer;
$normalizedHtml = HtmlNormalizer::fromHtml($rawHtml)->render();

Inlining CSS:
- External CSS: Pass as a string to inlineCss($css).
- Embedded CSS: Omit the argument to parse <style> blocks.
- Options: Chain modifiers like disableStyleBlocksParsing() or addExcludedSelector().

Post-Processing:

Cleanup: Remove display: none elements or redundant classes:

$prunedHtml = HtmlPruner::fromDomDocument($dom)
  ->removeElementsWithDisplayNone()
  ->removeRedundantClassesAfterCssInlined($cssInliner)
  ->render();

Visual Attributes: Convert CSS to HTML attributes (e.g., width: 100px → width="100"):

$visualHtml = CssToAttributeConverter::fromDomDocument($dom)
  ->convertCssToVisualAttributes()
  ->render();

CSS Variables: Resolve var(--variable) in inline styles:

$evaluatedHtml = CssVariableEvaluator::fromDomDocument($dom)
  ->evaluateVariables()
  ->render();

Integration Tips

Laravel Blade: Create a helper function in app/Helpers/EmailHelper.php:

use Pelago\Emogrifier\CssInliner;

if (!function_exists('emogrify')) {
    function emogrify($html, $css = null) {
        return CssInliner::fromHtml($html)->inlineCss($css)->render();
    }
}

Use in Blade:

{!! emogrify($emailTemplate, $styles) !!}

Service Provider: Register a service to handle email templating:

// app/Providers/EmailServiceProvider.php
public function register() {
    $this->app->singleton('emogrifier', function () {
        return new CssInliner();
    });
}

Queue Jobs: For async processing (e.g., sending emails):

// app/Jobs/ProcessEmail.php
public function handle() {
    $html = $this->emogrifier->fromHtml($this->template)->inlineCss($this->styles)->render();
    Mail::send([...], $html);
}

Testing: Use renderBodyContent() to isolate body content for unit tests:

$body = CssInliner::fromHtml($html)->inlineCss()->renderBodyContent();
$this->assertStringContainsString('style="color: red;"', $body);

Gotchas and Tips

Pitfalls

Selector Specificity:
- Partial Matches: addExcludedCssSelector('.example') won’t exclude p .example. Use universal selectors (e.g., .example, * .example) for broader exclusion.
- Pseudo-Classes: :hover, :active, etc., are not supported. Avoid dynamic styles.
Media Queries:
- Default allowed media types: all, screen, print. Add others with addAllowedMediaType().
- Outlook Quirk: Outlook ignores @media entirely. Exclude critical styles with addExcludedCssSelector().
HTML Structure:
- Missing Tags: HtmlNormalizer adds <head>/<body> if absent, but may alter structure. Test edge cases (e.g., <div><p></div>).
- Script/Style Blocks: Inlined <style> blocks are removed by default. Use disableStyleBlocksParsing() to preserve them.
CSS Variables:
- Scope: Variables must be defined in :root or an ancestor element to be resolved.
- Fallbacks: Unresolved variables (e.g., var(--undefined)) remain as-is.
Performance:
- Large HTML: Complex selectors (e.g., div.container > ul li:nth-child(2)) slow processing. Optimize selectors or use addExcludedSelector() for non-critical elements.
- Memory: DOM manipulation can be heavy. For batch processing, reuse DOMDocument instances:
```
$dom = new DOMDocument();
$dom->loadHTML($html);
$cssInliner = CssInliner::fromDomDocument($dom)->inlineCss($css);
```

Debugging Tips

Inspect Output: Use render() to see intermediate HTML. For debugging, log the DOM:

$dom = $cssInliner->getDomDocument();
file_put_contents('debug.html', $dom->saveHTML());

Selector Testing: Test selectors in isolation:

$html = '<div class="test">Hello</div>';
$css = '.test { color: red; }';
$result = CssInliner::fromHtml($html)->inlineCss($css)->render();

Common Issues:
- Styles Not Applied: Check for typos in selectors or excluded selectors.
- Broken Layout: Use HtmlNormalizer to fix malformed HTML.
- Outlook-Specific Bugs: Test with Litmus or Email on Acid.

Extension Points

Custom Processors: Extend AbstractHtmlProcessor to add steps (e.g., sanitization):

class CustomProcessor extends AbstractHtmlProcessor {
    public function addCustomAttribute() {
        $this->dom->documentElement->setAttribute('data-processed', 'true');
        return $this;
    }
}

Selector Extensions: Override getSupportedSelectors() in a custom CssInliner class to support unsupported selectors (e.g., :nth-child).

Post-Inlining Hooks: Use getDomDocument() to manipulate the DOM after inlining:

$dom = $cssInliner->getDomDocument();
$xpath = new DOMXPath($dom);
foreach ($xpath->query('//img') as $img) {
    $img->setAttribute('alt', 'Fallback');
}

Configuration: Centralize options in a config file (e.g., config/emogrifier.php):

return [
    'allowed_media' => ['all', 'screen', 'print', 'handheld'],
    'excluded_selectors' => ['.ad-banner', '.ad-banner *'],
];

Load in a service provider:

$cssInliner->addAllowedMediaType(config('emogrifier.allowed_media'));

Pro Tips

Email-Specific Optimizations:
- Tables: Use <table> for layout (better email client support). Inline border-collapse and width attributes.
- Fallbacks: Add !important to critical styles (e.g., color: red !important;).

Caching: Cache inlined HTML for static emails:

$cacheKey = md5($html . $css);
$inlinedHtml = Cache::remember($cacheKey, now()->addHours(1), function() use ($html, $css) {
    return CssInliner::fromHtml($html)->inlineCss($css)->render();
});

Testing Framework: Create a trait for Laravel tests:

trait EmogrifierTest {
    protected function assertInlinedStyles($expectedStyles, $html) {
        $inlined = CssInliner::fromHtml($html

Emogrifier Laravel Package