Css Inliner Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package. It ships a Twig tag ({% cssinline %}) that wraps tijsverkoyen/css-to-inline-styles. Laravel uses Blade, not Twig, and has no service provider auto-discovery for Symfony bundles. Day-to-day leverage in a Laravel app is therefore not direct — the bundle itself is essentially unusable without pulling in Twig and Symfony’s kernel.

Minimal steps for a Laravel developer:

1. Do not install eschmar/css-inliner-bundle. Install the underlying library instead:
   composer require tijsverkoyen/css-to-inline-styles
2. Look at the bundle’s README only to understand the concept: take HTML containing <style> blocks, inline those rules into matching elements, strip the <style> tags.
3. First real use case: email templates. Laravel Mailables render Blade to HTML; post-process that HTML with CssToInlineStyles before sending.

If you insist on inspecting the bundle, look at its Twig extension class — it is a thin wrapper around CssToInlineStyles::convert($html). That one method call is the entire value proposition.

Implementation Patterns

Because the bundle is Symfony-only, these patterns use the underlying CssToInlineStyles library directly inside Laravel.

Pattern 1 — Service wrapper (recommended)
Create a small service and bind it as a singleton:

namespace App\Services;

use TijsVerkoyen\CssToInlineStyles\CssToInlineStyles;

class CssInliner
{
    public function inline(string $html): string
    {
        $inliner = new CssToInlineStyles();
        $inliner->setCleanup(true);
        $inliner->setStripOriginalStyleTags(true);
        return $inliner->convert($html);
    }
}

Pattern 2 — Mailable integration
Override build() and render manually before inlining:

public function build()
{
    $html = view('emails.welcome', $this->data)->render();
    $inlined = app(CssInliner::class)->inline($html);
    return $this->html($inlined)->subject('Welcome');
}

Alternatively, listen to the MessageSending event and rewrite the body, but manual rendering is clearer.

Pattern 3 — Blade component
Mimic the Twig tag with a class component:

namespace App\View\Components;

use App\Services\CssInliner;
use Illuminate\View\Component;

class CssInline extends Component
{
    public function render()
    {
        return function (array $data) {
            return app(CssInliner::class)->inline($data['slot']);
        };
    }
}

Usage: <x-css-inline><style>...</style><p>...</p></x-css-inline>.

Pattern 4 — Blade directive (hacky)
Output buffering can work but is fragile with nested directives:

Blade::directive('cssinline', fn () => '<?php ob_start(); ?>');
Blade::directive('endcssinline', fn () => '<?php echo app(\App\Services\CssInliner::class)->inline(ob_get_clean()); ?>');

Prefer the component or service approach.

Integration tips

• Inline before queuing an email to keep workers fast, or inline inside a queued job if templates are dynamic.
• Cache inlined HTML for static templates (e.g., using Cache::remember).
• The bundle exposes no configuration; control CssToInlineStyles options in your own service.

Gotchas and Tips

• Not Laravel-compatible: No service provider, no Blade support, no config. Composer will pull Symfony/Twig dependencies that may conflict with Laravel’s versions. Avoid installing the bundle.
• Maintenance risk: Last release March 2020, Symfony 4/5 only, 6 stars, 0 dependents. The bundle is stale. The underlying library is maintained by a well-known author, so use that instead.
• CSS limitations: CssToInlineStyles handles simple selectors well but does not support media queries, pseudo-classes, or complex combinators. It may strip <style> tags entirely, losing responsive email styles. Test with real email clients (Gmail, Outlook).
• Performance: Inlining is CPU-bound. For high-volume mail, inline in a queued job and cache results where possible.
• Security: The library does not sanitize HTML or CSS. Only inline templates you control; user-supplied CSS could be an injection vector.
• Debugging: If styles disappear, set setCleanup(false) and inspect the before/after HTML. Log both versions during development.
• Extension points: The bundle has none beyond the Twig tag. Your Laravel service is the extension point — add options, caching, logging there.
• Alternatives: For Laravel-native CSS inlining, evaluate packages like fedeisas/laravel-mail-css-inliner or spatie/laravel-mail-css-inliner (check maintenance status). They integrate with Laravel’s mailer and Blade directly, which is a far better day-to-day fit than a Symfony bundle.