Tailwind Merge Php Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tales-from-a-dev/tailwind-merge-php
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       TalesFromADev\TailwindMerge\TailwindMergeServiceProvider::class,
   ],
   

2. Basic Usage: Inject the TailwindMerge facade into a Blade view or controller:

   use TalesFromADev\TailwindMerge\Facades\TailwindMerge;
   
   $mergedClasses = TailwindMerge::merge([
       'bg-blue-500 hover:bg-blue-700',
       'bg-red-500 hover:bg-red-700',
       'p-4',
       'text-center'
   ]);
   // Output: "bg-blue-500 hover:bg-blue-700 hover:bg-red-700 p-4 text-center"
   

3. Blade Helper: Use the @tailwindMerge directive in Blade:

   @tailwindMerge([
       'bg-blue-500 hover:bg-blue-700',
       'bg-red-500 hover:bg-red-700',
       'p-4'
   ])
   

Implementation Patterns

Workflows

1. Dynamic Class Merging: Merge classes dynamically based on user roles, device detection, or other runtime logic:

   $classes = [];
   if (auth()->check()) {
       $classes[] = 'bg-green-500';
   } else {
       $classes[] = 'bg-gray-500';
   }
   $classes[] = 'hover:bg-blue-500 p-4';
   return TailwindMerge::merge($classes);
   

2. Component-Based Merging: Use in Laravel components to merge static and dynamic classes:

   class CardComponent extends Component
   {
       public function classes(): array
       {
           return [
               'border rounded-lg shadow-md',
               $this->isHighlighted ? 'border-blue-500' : 'border-gray-200',
               'p-6',
           ];
       }
   
       public function render()
       {
           return view('components.card', [
               'classes' => TailwindMerge::merge($this->classes()),
           ]);
       }
   }
   

3. Form Request Validation: Merge classes conditionally based on validation errors:

   $classes = ['p-4'];
   if ($errors->has('email')) {
       $classes[] = 'border-red-500';
   }
   return TailwindMerge::merge($classes);
   

Integration Tips

• View Composers: Pre-merge classes in a view composer for global reuse:

  View::composer('*', function ($view) {
      $view->with('globalClasses', TailwindMerge::merge([
          'font-sans',
          config('app.theme') === 'dark' ? 'dark:bg-gray-800' : 'bg-white',
      ]));
  });
  

• Livewire/Alpine.js: Merge classes reactively in Livewire or Alpine.js:

  // Livewire component
  public $isActive = false;
  public function classes()
  {
      return TailwindMerge::merge([
          'p-4',
          $this->isActive ? 'bg-blue-500 text-white' : 'bg-gray-200',
      ]);
  }
  

• Tailwind Config: Extend the package’s default Tailwind config by publishing the config file:

  php artisan vendor:publish --provider="TalesFromADev\TailwindMerge\TailwindMergeServiceProvider" --tag="config"
  

  Customize config/tailwind-merge.php to add/remove merge rules. Note: Ensure supported_versions includes v4.3 for Tailwind CSS 4.3 support:

  'supported_versions' => ['v3.0', 'v3.1', 'v3.2', 'v4.3'],
  

Gotchas and Tips

Pitfalls

1. Performance Overhead:

   • Avoid merging large arrays of classes in tight loops. Cache merged results when possible:

     $merged = Cache::remember('merged_classes_key', now()->addHours(1), function () {
         return TailwindMerge::merge($largeClassArray);
     });
     

2. Unexpected Conflicts:

   • Tailwind’s default merge rules may not cover all edge cases (e.g., arbitrary values like bg-[color:var(--custom)]). Extend the config to handle custom rules:

     'custom_rules' => [
         'arbitrary' => [
             'pattern' => '/bg-\[.*\]/',
             'strategy' => 'append', // or 'prepend'
         ],
     ],
     

3. Blade Directive Scope:

   • The @tailwindMerge directive only works in Blade files. For non-Blade templates (e.g., Inertia.js), use the facade directly.

4. Static Analysis Tools:

   • Some static analyzers (e.g., PHPStan) may flag TailwindMerge::merge() as "unused" if the result isn’t stored or returned. Add @phpstan-ignore-next-line if needed.

5. Tailwind CSS 4.3 Compatibility:

   • Ensure your project’s Tailwind CSS version is compatible with the package. If using Tailwind CSS 4.3, verify the supported_versions in config/tailwind-merge.php includes v4.3. If not, publish and update the config as shown above.

Debugging

• Inspect Merged Output: Use the debug() method to see the merge process:

  TailwindMerge::debug()->merge($classes);
  // Outputs: "Merged classes: [final_output] | Conflicts resolved: [conflicts]"
  

• Log Conflicts: Enable logging in config/tailwind-merge.php:

  'log_conflicts' => true,
  

  Check storage/logs/laravel.log for conflict details.

Extension Points

1. Custom Merge Strategies: Override the default merge logic by binding your own resolver:

   TailwindMerge::extend(function ($classes) {
       // Custom logic here
       return $classes;
   });
   

2. Plugin System: Use the TailwindMerge::macro() method to add reusable merge patterns:

   TailwindMerge::macro('button', function ($classes) {
       return TailwindMerge::merge([
           'px-4 py-2 rounded-md',
           ...$classes,
       ]);
   });
   // Usage: TailwindMerge::button(['bg-blue-500', 'hover:bg-blue-700'])
   

3. Tailwind Version Compatibility: If using Tailwind CSS 4.3, ensure the supported_versions in config/tailwind-merge.php includes v4.3:

   'supported_versions' => ['v3.0', 'v3.1', 'v3.2', 'v4.3'],