Weave Code
Twig Tailwind Extra Laravel Package
tales-from-a-dev/twig-tailwind-extra
A Twig extension adding Tailwind CSS filters: tailwind_merge() integrates tailwind-merge-php to resolve conflicting utility classes, while tailwind_classes() builds mergeable class lists for Twig's html_attr() and html_attr_merge(). Requires PHP 8.1+, Twig 3+, and Tailwind 4+.
Twig Tailwind Extra is a Twig extension that brings Tailwind CSS class handling to your templates. It registers two filters — tailwind_merge() for conflict-aware class merging via tailwind-merge-php, and tailwind_classes() for building mergeable class lists that plug into Twig's html_attr()/html_attr_merge().
- Conflict resolution: merges competing utilities, keeping the last one.
- Attribute-ready: class lists work directly with
html_attr_merge(). - Simple setup: supports PHP ≥ 8.1, Twig ≥ 3.0 and Tailwind ≥ 4.0.
- Semantic versioning: predictable, stable merged output.
Frequently asked questions about Twig Tailwind Extra
- What does tales-from-a-dev/twig-tailwind-extra actually do?
- It is a Twig extension that exposes Tailwind-aware filters so your templates can build class attributes without duplicate or conflicting utilities. It wraps the tailwind-merge-php library behind a tailwind_merge() filter and adds tailwind_classes() for constructing a mergeable class list that works with Twig's html_attr() and html_attr_merge(). Instead of hand-managing conditional class strings, you pass everything through the merger and let the last conflicting utility win.
- How do I install twig-tailwind-extra with Composer?
- Run composer require tales-from-a-dev/twig-tailwind-extra in the project that renders your Twig templates. The package requires PHP 8.1 or newer, Twig 3.0 or newer, and a Tailwind 4.0+ setup, so check those constraints before updating. If you use Symfony, the extension is typically picked up automatically through service autoconfiguration; otherwise register it manually with your Twig environment.
- How do I register the Twig extension in a Laravel or Symfony app?
- In Symfony, extensions implementing the Twig extension interface are usually auto-tagged as twig.extension via autoconfigure, so no manual wiring is needed after install. Laravel does not ship Twig by default, so you would only use this package if you have installed a Twig bridge or Twig environment package and can register the extension on that environment. Registering the extension is all it takes; both filters become available globally in your templates.
- What is the difference between tailwind_merge() and tailwind_classes()?
- tailwind_merge() runs a class string through the tailwind-merge-php conflict resolver and returns a single, deduplicated utility list. tailwind_classes() builds a mergeable list of classes, typically from conditionals or arrays, intended for use with Twig's html_attr() or html_attr_merge() so attribute rendering stays clean. Use the merge filter for a final string and the classes filter when you are composing attributes from multiple template fragments.
- Can I use this package in a Laravel Blade app?
- Not directly: the package is a Twig extension, so Blade templates cannot call its filters. Laravel projects can use it only when a Twig environment is present, for example through a Twig bridge package, and in that case you register the extension on that environment. Laravel Blade users generally need a different approach for class merging. The underlying tailwind-merge-php library is framework-agnostic and can be called from PHP directly.
- Which PHP, Twig, and Tailwind versions are supported?
- The package requires PHP 8.1 or higher, Twig 3.0 or higher, and Tailwind 4.0 or higher. Twig 4 support was added in v1.5.0 while Twig 3 remains supported, so existing projects do not need to upgrade. Because the merge logic assumes modern Tailwind semantics, validate behaviour carefully if you are on older Tailwind setups.
- Does this package support Twig 4?
- Yes, version 1.5.0 added Twig 4 compatibility, making the package usable in projects planning a templating engine upgrade. The addition is non-disruptive because Twig 3 support was kept, so the constraint does not force an upgrade. If you are migrating to Twig 4, this release clears a dependency blocker you would otherwise hit.
- Will upgrading to v1.5.0 change the CSS classes my templates output?
- Possibly, because v1.5.0 moves the underlying tailwind-merge-php constraint from 0.3 to 0.5, and merge fixes can change output for edge cases. The public API is unchanged, but the package explicitly notes that a minor release may alter merged output where the merger fixed a bug. Diff your actual class vocabulary between versions before rolling out, especially if you rely on best-effort merges.
- Which edge cases should I test after upgrading?
- Focus on arbitrary value utilities such as w-[calc(100%-1rem)], stacked variants like dark:hover:md:shadow-lg, and any utilities generated by Tailwind plugins or custom theme extensions. If you configured a prefix in your Tailwind setup, verify prefixed classes still merge as expected. Also confirm that custom spacing and font scale values are interpreted the same way by the newer merge engine.
- What alternatives exist if I need class merging outside Twig?
- The merge engine itself is tailwind-merge-php, published by the same maintainer, and can be used directly from PHP without Twig at all. That is the usual route for Blade or plain PHP templates, or when you want to control the library version independently of this extension. Using the extension is mainly about convenience and keeping template code declarative. The package is MIT licensed, so you can also fork or wrap it.
Weaver
How can I help you explore Laravel packages today?