Template Extension Bundle Laravel Package

Getting Started

This release (2.1.0) is a minor feature addition — a dark mode tool merged via PR #2 — so existing installs should upgrade without breaking changes.

• Install: composer require os2display/template-extension-bundle:^2.1
• Important framing: despite the "Laravel/PHP" label, this is an OS2Display Symfony bundle, not a native Laravel package. In a Laravel app you'll typically consume it as a plain Composer dependency (e.g. for its Twig extensions/template helpers) or wrap it in a custom service provider; you won't get the bundle's autoconfiguration for free.
• Look first at: the bundle's Twig extension classes and the new dark mode tool added in PR #2. That PR is the only change in this release, so it is the first thing to evaluate.
• First use case: expose a dark mode toggle/filter in your OS2Display templates so slide/template rendering can switch themes without duplicating templates.

If you are on Laravel + Blade rather than Symfony + Twig, treat the package primarily as a reference implementation of the dark mode logic and port the relevant filter/helper into a Blade directive or view composer.

Implementation Patterns

• Symfony-native usage: register the bundle in config/bundles.php, let autoconfiguration pick up the Twig extensions, then call the dark mode helper/filter from your template Twig files.
• Laravel integration: create a small service provider that binds the bundle's extension classes into the container and registers any Twig environment (if using TwigBridge) or expose an equivalent Blade directive. Keep this adapter thin so upgrades stay easy.
• Theme toggling pattern: drive dark mode from a single source of truth (a cookie, user preference, or tenant setting) and pass that flag into the template renderer rather than branching inside every template. The new tool should be the single switch point.
• Asset/CSS contract: pair the dark mode tool with CSS custom properties or a .dark class on the root element; the PHP side should only emit the flag/class, not inline styles.
• Upgrade workflow: pin to ^2.1, run your template rendering test suite, and visually diff light/dark output for at least one representative template before rolling out.

Gotchas and Tips

• Symfony/Laravel mismatch: bundle registration, config trees, and Twig extension autoconfiguration do not carry over to Laravel. Budget adapter work; don't assume composer require is enough.
• Release scope is tiny: 2.1.0 contains only the dark mode tool. If you don't need dark mode, this release is a low-risk no-op — but there's also little new to gain beyond it.
• Cache clearing: after upgrading, clear Symfony cache (bin/console cache:clear) or Laravel's compiled views/config (php artisan view:clear && php artisan config:clear) — stale Twig/Blade caches are the most common "the new filter doesn't exist" cause.
• Extension registration debugging: if the dark mode helper is undefined, verify the Twig extension is actually tagged/registered; in Laravel+TwigBridge confirm the extension is added to the Twig environment, not just the container.
• Version constraints: ensure your Symfony/Twig (or TwigBridge) versions satisfy the bundle's composer.json requirements; minor releases can quietly raise these.
• Extension points: the cleanest long-term approach is to wrap the bundle's dark mode logic behind your own interface/directive, so a future breaking change in the bundle doesn't leak into every template.
• Verify the PR: since the release notes are a single line, read PR #2 to confirm the expected API surface (filter vs. function vs. service) before writing templates against it.