Twig Bundle Laravel Package

Getting Started

1. Install via Composer. composer require lidaa/twig-bundle — but be aware this is a Symfony bundle (LidaaTwigBundle), not a Laravel package. There is no service provider or facade. If you're on Symfony, register it in config/bundles.php:

   Lidaa\TwigBundle\LidaaTwigBundle::class => ['all' => true],
   

   If you're on Laravel, do not expect it to drop into the container — either run it under rcrowe/twigbridge by grabbing the extension classes, or treat it as a reference implementation to vendor.

2. No config file is needed. Every extension (php, image, url, css, js, tag, session, number, sf, unset, form, html) is registered with the twig.extension tag, so functions/filters become available as soon as the bundle boots.

3. Look here first for discovery: php bin/console debug:twig (Symfony) or the equivalent list command under twigbridge. Grep for the prefixes (php_, css, js, image, tag, session, number, sf, unset, form, html) to find the exact callable names without reading source.

4. First real use case: you're in a template and default Twig doesn't provide a helper you already have in a controller — e.g. emitting <link>/<script> tags from an array (css([...]), js([...])), rendering an <img> with attributes (image(src, alt, w, h)), reading a session value (session('key')), or calling a whitelisted PHP function (php_function('strtoupper', name)). Start with the safe ones (css/js/image/number) and only reach for php/session when you've reviewed the risk.

Implementation Patterns

• Shared base template with per-page asset arrays. Put {{ css(assets.css) }} and {{ js(assets.js) }} in base.html.twig, and pass a assets array per action. This is the cleanest day-to-day win — it replaces hand-written <link>/<script> blocks.
• Image markup from data arrays. When image metadata (src, alt, width, height) lives in one array (CMS row, media model), pass the whole thing to image(...) instead of templating <img> attributes by hand.
• Locale-aware number formatting. Use the number extension alongside Symfony's framework.default_locale (or set locale per request) so currency/percent output is consistent. Don't chain |number_format calls with hardcoded separators.
• Session reads for flash-style values. session('key') is fine for one-off flashes; for structured data, pass a view model from the controller and keep templates dumb. Session state in templates is invisible to your controller tests.
• unset after polluting includes. If an {% include %} leaks context into the parent, unset is the pragmatic escape hatch — but treat every use as a signal that your partial's context is wrong.
• php_function(...) as a last resort only. Prefer a Twig filter, a custom extension, or a view-model method. If you must call out, restrict the argument to the name of a function already safe to expose in a controller.
• Form/HTML extensions for legacy templates. Useful when porting pre-Form-component templates — you get widget and tag markup without rewriting. For new Symfony work, prefer Symfony Forms' own themes.
• Override or extend, don't fork. Extensions are plain Twig\Extension\AbstractExtension services tagged twig.extension, so a decorator with decoration_priority lets you tweak behavior without editing vendor code.

Gotchas and Tips

• The php extension is a security footgun. Any template that renders user-editable content must never reach php_function(...); it defeats Twig's sandbox. Disable the extension entirely if you don't need it (register the service without the twig.extension tag, or decorate it away).
• Heavy overlap with Symfony's twig-bridge. path(), url(), asset(), form_*, html_*, session, trans already exist in modern Symfony. The bundle's versions may shadow or slightly differ. Before assuming which wins, check debug:twig --filter=your_function.
• Twig 3 drift is real. The extension inventory uses Twig 1.x conventions (getName(), initRuntime, Twig_Extension base). Expect mechanical rewrites (removing getName, extending AbstractExtension) if you lift these onto Laravel's Twig 3.
• Package is stale (24★, 0 dependents). Pin the exact commit in composer.json, plan to vendor/fork, and re-test on every Symfony/Twig major. Failures usually appear as "function not found" or changed signatures, not crashes.
• Debugging a missing function: run php bin/console debug:twig --filter=foo. If it's absent, the extension didn't load — check bundle registration and the twig.extension tag on the service before assuming a bug in the extension itself.
• Configuration quirks: this bundle is intentionally zero-config. Locale for number, asset paths for image/css/js, and session scoping must be driven by framework config or a decorator — there is no bundle-level toggle sheet.
• Laravel path: since there's no service provider, "using it in Laravel" means porting the extension classes into a twigbridge-registered extension and rewiring Symfony-coupled bits (session, form, sf, anything on RequestStack/TranslatorInterface). The css, js, tag, html, unset, and number extensions are the most portable.
• Prefer macros when the win is narrow. If you only need one <script> tag or one <img>, a Twig macro is clearer and safer than pulling in a whole extension. This bundle earns its keep when a template uses several of these helpers together.