Tailwind Merge Php Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require gehrisandro/tailwind-merge-php
   

   Ensure your project uses PHP 8.1+ and Tailwind CSS v3.0–v3.4.

2. First Use Case: Resolve a simple class conflict in a Blade template or Livewire component:

   use TailwindMerge\TailwindMerge;
   
   $mergedClasses = TailwindMerge::instance()->merge('text-red-500', 'text-blue-500');
   // Output: 'text-blue-500'
   

   Use the result directly in Blade:

   <div class="{{ $mergedClasses }}">Merged Text</div>
   

3. Where to Look First:

   • README.md: For basic usage, configuration, and examples.
   • TailwindMerge::instance(): Default singleton for quick merges.
   • TailwindMerge::factory(): For custom configurations or caching.
   • Changelog: To verify compatibility with your Tailwind version.

Implementation Patterns

Core Workflows

1. Blade Templates

Dynamically merge classes based on runtime logic (e.g., user roles, themes):

@php
    $baseClasses = 'bg-gray-100 hover:bg-gray-200';
    $userClasses = 'dark:bg-blue-800';
    $merged = TailwindMerge::instance()->merge($baseClasses, $userClasses);
@endphp
<div class="{{ $merged }}">Dynamic Background</div>

2. Livewire/Alpine.js

Resolve conflicts in real-time updates without client-side flicker:

// Livewire Component
public function updateClasses()
{
    $this->mergedClasses = TailwindMerge::instance()->merge(
        'p-4 border border-gray-300',
        '!p-6 border-red-500'
    );
    // Output: '!p-6 border-red-500'
}

<div class="{{ $mergedClasses }}">Livewire Merged</div>

3. Dynamic Component Libraries

Standardize class merging across shared components:

// Button Component
public function render()
{
    $classes = TailwindMerge::instance()->merge(
        'px-4 py-2 rounded',
        $this->variant === 'primary' ? 'bg-blue-600 text-white' : 'bg-gray-200'
    );
    return view('components.button', ['classes' => $classes]);
}

4. API-Driven HTML

Merge classes in server-rendered responses (e.g., emails, PDFs):

$emailClasses = TailwindMerge::instance()->merge(
    'text-lg font-sans',
    $user->prefersDarkMode ? 'dark:text-gray-300' : 'text-gray-800'
);
$mailer->send([...], view('emails.welcome', ['classes' => $emailClasses]));

5. Theming Systems

Resolve tenant/user-specific styles:

$tenantClasses = TailwindMerge::instance()->merge(
    'bg-white text-black',
    Tenant::find($id)->themeClasses
);

Integration Tips

Caching for Performance

Enable PSR-16 caching (e.g., Laravel’s cache) for high-frequency merges:

use Illuminate\Cache\CacheManager;

$cache = app(CacheManager::class)->store('file');
$cachedMerge = TailwindMerge::factory()->withCache($cache)->make();

Clear cache when updating Tailwind config:

php artisan cache:clear

Custom Tailwind Config

Extend default class groups for custom utilities:

$customMerge = TailwindMerge::factory()->withConfiguration([
    'classGroups' => [
        'font-size' => [
            ['text' => ['custom-large']]
        ],
    ],
])->make();

Reference: Original Config Docs.

Arbitrary Values

Handle dynamic classes like CSS variables:

$merged = TailwindMerge::instance()->merge(
    'bg-[var(--primary)]',
    'bg-blue-500'
);
// Output: 'bg-blue-500' (if no var(--primary) is defined)

Stateful Classes

Merge hover/focus states reliably:

$merged = TailwindMerge::instance()->merge(
    'hover:bg-gray-200',
    'focus:bg-blue-100'
);
// Output: 'hover:bg-gray-200 focus:bg-blue-100'

Non-Tailwind Classes

Preserve non-Tailwind classes while merging:

$merged = TailwindMerge::instance()->merge(
    'custom-class block',
    'inline'
);
// Output: 'custom-class inline'

Gotchas and Tips

Pitfalls

1. Configuration Mismatch:

   • Issue: Custom Tailwind configs (e.g., renamed colors, custom spacing) may break merging.
   • Fix: Extend classGroups in the configuration:

     'classGroups' => [
         'colors' => [
             ['bg' => ['custom-blue']],
         ],
     ],
     

   • Debug: Test with TailwindMerge::instance()->getConfiguration() to verify loaded rules.

2. Arbitrary Value Conflicts:

   • Issue: Arbitrary values (e.g., z-[999], [&>*]:underline) may not merge as expected.
   • Fix: Ensure your Tailwind config includes the arbitrary variants:

     // tailwind.config.js
     module.exports = {
         corePlugins: {
             preflight: false,
         },
         important: true,
         variants: {
             extend: {},
         },
         plugins: [],
     };
     

   • Workaround: Use explicit configurations for custom arbitrary rules.

3. Caching Stale Data:

   • Issue: Cached merges may persist after Tailwind config updates.
   • Fix: Clear the cache manually or use a cache key tied to the config hash:

     $cacheKey = 'tailwind_merge_' . md5(file_get_contents(config_path('tailwind.php')));
     $cache->remember($cacheKey, now()->addHours(1), fn() => $mergedClasses);
     

4. PHP 8.1+ Requirement:

   • Issue: Older PHP versions will fail silently or throw errors.
   • Fix: Update your php.ini or use a Docker/PHP-FPM image with PHP 8.1+.

5. Dark Mode Quirks:

   • Issue: Dark mode classes (dark:...) may not merge predictably if the base class is missing.
   • Fix: Always include a base class for dark mode:

     $merged = TailwindMerge::instance()->merge(
         'text-black dark:text-white',
         'dark:text-gray-700'
     );
     // Output: 'text-black dark:text-gray-700'
     

6. Important Modifier (!):

   • Issue: The ! modifier may not behave as expected in all contexts.
   • Fix: Place ! classes last in the merge order:

     $merged = TailwindMerge::instance()->merge(
         'font-medium',
         '!font-bold'
     );
     // Output: '!font-bold'
     

Debugging Tips

1. Inspect Merged Classes: Use TailwindMerge::instance()->debugMerge() to see intermediate steps:

   $debug = TailwindMerge::instance()->debugMerge('p-4 px-6');
   // Output: ['p-4', 'px-6'] → ['px-6']
   

2. Validate Tailwind Config: Ensure your tailwind.config.js matches the package’s assumptions:

   • Default color names (e.g., red-500, not primary-500).
   • Standard utility prefixes (e.g., bg-, text-, not custom-bg-).

3. Test Edge Cases:

   • Breakpoints: lg:p-4 md:p-6 → lg:p-6 md:p-6.
   • States: hover:text-red-500 focus:text-blue-500 → merged as-is.
   • Arbitrary: z-10 z-[999] → z-[999].

4. Fallback for Unsupported Cases: If merging fails, fall back to the last class:

   $merged = TailwindMerge::instance()->merge(...);
   $fallback = end(explode(' ',