- How do I install tailwind-merge-php in a Laravel application?
- Install it with Composer using composer require gehrisandro/tailwind-merge-php. In Laravel you can call TailwindMerge::instance()->merge(...) directly in Blade components, Livewire actions, or resource transformers, or use the separate tailwind-merge-laravel wrapper for a service provider and Blade directive. The package requires PHP 8.1+ and has no framework dependency.
- Does tailwind-merge-php support Tailwind CSS v4?
- No. The package documents support for Tailwind v3.0 through v3.4 only, and Tailwind v4's CSS-first configuration and changed utility semantics are not covered. If Tailwind v4 is on your roadmap, treat this package as a dead end until it is ported or forked. Check upstream tailwind-merge for any v4 story that this PHP port could follow.
- Which Laravel and PHP versions are supported by tailwind-merge-php?
- The core package requires PHP 8.1+ and has no Laravel dependency, so it coexists with Laravel 9, 10, and 11 lines. For Laravel-specific integration such as a facade or Blade directive, use the sibling tailwind-merge-laravel package. Verify the wrapper's release cadence against the core package before adopting it.
- How do I configure custom Tailwind classes in tailwind-merge-php?
- Use TailwindMerge::factory()->withConfiguration([...]) to adjust class groups and other options. Any custom tailwind.config.js extensions, such as custom spacing, renamed colors, plugin utilities, or prefixes, must be mirrored in PHP configuration. Otherwise merges may succeed silently while producing incorrect output, creating a maintenance and correctness hazard.
- Should I use tailwind-merge-php or tailwind-merge-laravel?
- Use tailwind-merge-laravel if you want a Laravel service provider, facade, and Blade directive out of the box; it is the recommended entry point for Laravel apps. Use the core tailwind-merge-php package for framework-agnostic PHP services, queue workers, or when you want to wire it yourself. Check that the wrapper's release cadence tracks the core package.
- How does caching work in tailwind-merge-php and should I enable it?
- The package offers an optional PSR-16 cache, which maps cleanly onto Laravel's cache repository. Enable it when merging happens at request-time render or during queued mail and PDF generation where repeated class strings are common. If merging is done at build time, caching may be unnecessary.
- Can tailwind-merge-php handle arbitrary values, variants, and the important modifier?
- Arbitrary values, arbitrary variants, the important modifier, and stacked variants are supported, but these are exactly the areas where historical bugs landed in v1.1.1 and v1.1.2. If your design system relies on them for theming, carry a fixture-based test suite of your real-world class strings. This helps catch silent correctness issues after upgrades.
- Is tailwind-merge-php framework-agnostic and usable outside Laravel?
- Yes. It is a pure-PHP, stateless utility with no Laravel coupling, and v1.0.0 explicitly removed the illuminate/support dependency. It only requires PHP 8.1+ and a PSR-4 autoloader, so it fits Blade components, Livewire actions, API transformers, domain layers, or non-Laravel PHP services. You can wrap it behind an internal ClassMerger interface to insulate call sites from the vendor.
- What are alternatives to tailwind-merge-php for merging Tailwind classes in PHP?
- The main alternative is the JavaScript tailwind-merge library, but that requires Node or a build step and does not fit request-time PHP rendering. You could implement your own conflict resolver or fork this package, which is MIT licensed and viable if the maintainer stops. For Laravel projects, the sibling tailwind-merge-laravel wrapper is the closest alternative entry point.
- How should I test tailwind-merge-php to avoid incorrect merges with custom configuration?
- Build a fixture-based test suite using your real-world class strings, especially arbitrary values, variants, shadows, borders, and custom utilities. Assert the exact merged output rather than only checking that no exception is thrown. Keep the PHP configuration in sync with tailwind.config.js and add tests when design tokens change.