Twig Extra Bundle

Twig’s core engine ships without extras like Markdown rendering, Intl-aware filters, or CSS inlining — those live in separate twig/*-extra packages so the core stays small. The Twig Extra Bundle is the Symfony integration layer that detects which of those extra packages are installed via Composer and automatically registers the corresponding Twig extension in the templating engine, with no manual service configuration required.

It ships a MissingExtensionSuggestor that produces a helpful error pointing at the right composer require command if a template uses an extra filter/function/tag whose backing package isn’t installed yet, making the extras system self-documenting inside a Symfony application.

What You Get

• Automatic detection and registration of installed twig/*-extra packages (Markdown, Intl, HTML, String, CSS-inliner, Inky, Cache) as Twig extensions.
• A MissingExtensionSuggestor that raises a clear error naming the exact composer require twig/*-extra command needed when a template calls a filter/function from an extra that isn’t installed.
• A LeagueCommonMarkConverterFactory that wires the league/commonmark library as the Markdown extension’s rendering backend when twig/markdown-extra is installed.
• Symfony DependencyInjection integration (Configuration.php, TwigExtraExtension.php, a compiler pass) so the extensions register as proper, cacheable Symfony services.
• Zero-configuration defaults — the bundle works purely by presence of the relevant Composer packages, requiring no bundle-specific config in the common case.

Common Use Cases

• Rendering Markdown content directly in Twig templates via the markdown_to_html filter, backed by league/commonmark.
• Using locale-aware number, date, and currency formatting filters from twig/intl-extra in a multi-language Symfony app.
• Inlining CSS into HTML emails sent from a Symfony application via twig/cssinliner-extra and twig/inky-extra.
• Getting immediate, actionable errors when a developer uses an extra Twig filter without having installed its backing package yet.

Under The Hood

Architecture: TwigExtraBundle.php is the standard Symfony bundle entry point; DependencyInjection/TwigExtraExtension.php and DependencyInjection/Configuration.php implement Symfony’s extension/configuration contract, while DependencyInjection/Compiler/ holds a compiler pass that inspects the container for installed extra packages. Extensions.php is the central registry: a const EXTENSIONS array maps each extra’s short name (cache, html, markdown, intl, string, cssinliner, inky) to its extension class, its Composer package name, and the filters/functions/tags it provides — this single source of truth drives both the auto-registration logic and the MissingExtensionSuggestor’s error messages.

Tech Stack: PHP 8.1+, requires symfony/framework-bundle, symfony/twig-bundle, and twig/twig ^3.2 or ^4.0 as its runtime dependencies; each individual extra (league/commonmark, twig/markdown-extra, twig/intl-extra, etc.) is a dev-dependency here because the bundle only needs them present at test time — in production they’re installed by the consuming application as needed.

Code Quality: Tests/IntegrationTest.php and Tests/DependencyInjection/ exercise the bundle’s container wiring end-to-end using symfony/phpunit-bridge, with Tests/Fixture/ providing sample Symfony kernel configurations. As an official Twig/Symfony-maintained package it follows the same CI and backward-compatibility conventions as the rest of the Symfony/Twig ecosystem, though its own commit cadence is modest (well under one commit per month on average) since the bundle’s surface area is small and stable.

API Design: The bundle deliberately has almost no public API of its own — its entire value is that a developer never calls anything explicitly; installing an extra package and referencing its filter in a template is the whole integration story, with MissingExtensionSuggestor acting as the safety net when that assumption is violated.