- How do I install pelago/emogrifier in a Laravel application?
- Run composer require pelago/emogrifier in your Laravel project; it is a framework-agnostic PHP library rather than a Laravel package with auto-discovered providers. Instantiate the CssInliner class where you prepare email HTML, or bind it in a small service provider for dependency injection. Then pass your rendered Blade HTML through the inliner before sending the Mailable.
- Can I use pelago/emogrifier with Laravel Blade and Mailables?
- Yes. Render your Blade or Mailable HTML first, then run the resulting string through Emogrifier before handing it to Laravel's mailer. Many teams wrap this in a service, a custom Blade directive, or a Mailable hook so templates stay readable. Keep the inlining step explicit so you can log, catch exceptions, and test the final email HTML.
- Which PHP and Laravel versions does pelago/emogrifier support?
- Emogrifier is framework-agnostic, so Laravel support depends on PHP and Composer constraints rather than a Laravel service provider. As of v8.3.0 it supports PHP 8.6 and formally deprecates PHP 7.3, so use a currently supported PHP version for your Laravel release. Check the package's composer.json before upgrading in older Laravel applications.
- How does Emogrifier inline CSS from style and link tags?
- Emogrifier can parse a full HTML document, including CSS from style elements and link stylesheet references, then apply matching rules as inline style attributes. This helps with email clients that discard embedded stylesheets. Load complete HTML through the inliner rather than isolated fragments when you depend on document-level style discovery.
- What CSS selectors does Emogrifier support?
- Emogrifier supports element, class, ID, and combinator selectors, which covers most typical email CSS. Support for modern CSS is partial; for example, it does not handle :hover or media queries beyond all, screen, and print. Design email styles within that subset and allowlist selectors when needed.
- Why is Emogrifier not inlining CSS in production after upgrading to 8.3.0?
- In v8.3.0, regex blowouts no longer throw in production by default; they raise a trigger_error() and return the original HTML unmodified, while exceptions occur only when the debug option is enabled. That means a pathological template can send un-inlined HTML and render poorly in Outlook or Gmail. Enable debug outside production, route trigger_error() into Laravel logging or alerts, and canary-render critical templates in CI.
- How should I handle exceptions from Emogrifier render() in Laravel?
- Since v8.3.0, render() can throw when an internal DOMDocument error occurs instead of returning an empty string. Wrap calls in try/catch within your Mailable or email service, log the failure, and choose a deliberate fallback such as sending raw HTML or failing the queued job for retry. Do not assume render() always returns a string.
- Is pelago/emogrifier suitable for long-running Laravel queue workers?
- Yes, v8.3.0 clears internal caches on each invocation, addressing the memory growth that could affect long-lived Laravel queue workers and Horizon fleets. You should still monitor memory and benchmark unusually large or malformed templates. Running inlining in queued jobs remains a sensible pattern for transactional email workloads.
- What performance issues should I expect with Emogrifier on large HTML emails?
- Emogrifier uses DOMDocument and may add latency and memory overhead when processing large HTML emails. Benchmark with realistic templates, such as around 50KB, before enabling it for every message. For high-volume sending, perform inlining asynchronously in a Laravel queue and validate HTML input to avoid malformed-document costs.
- Is pelago/emogrifier actively maintained and well tested compared with alternatives?
- Emogrifier is actively maintained, has high test coverage, and v8.3.0 adds PHP 8.6 support while fixing deep nesting and cache-clearing issues. Alternatives include tijsverkoyen/css-to-inline-styles and hosted CSS inlining services, but compare their PHP constraints, selector support, and maintenance activity. For Laravel projects, choose based on Composer compatibility and how much control you need over error handling.