Getting Started

Minimal Setup

Installation

composer require tales-from-a-dev/twig-tailwind-extra

TalesFromADev\TwigTailwindExtra\TwigTailwindExtraServiceProvider::class,

Publish Config (Optional)
```
php artisan vendor:publish --provider="TalesFromADev\TwigTailwindExtra\TwigTailwindExtraServiceProvider"
```
Edit config/twig-tailwind-extra.php to define your Tailwind config path (default: tailwind.config.js).
First Use Case In a Twig template, leverage the tailwind() function to generate utility classes dynamically:
```
<div class="{{ tailwind('bg-blue-500 hover:bg-blue-700 text-white') }}">
    Hover me!
</div>
```

Implementation Patterns

Dynamic Class Generation with Tailwind Merge

Leverage the updated tailwind-merge-php (v0.3) for smart class merging and conflict resolution:

{# Merges conflicting classes automatically #}
<div class="{{ tailwind('bg-blue-500 hover:bg-blue-700 text-white p-4 p-6') }}">
    Conflicts resolved!
</div>

Conditional and Responsive Classes

{# Responsive + conditional #}
<div class="{{ tailwind(
    is_active ? 'bg-green-500' : 'bg-gray-300',
    'md:p-6 lg:p-8'
) }}">
    Dynamic + responsive
</div>

Custom Directives (Enhanced)

Extend Tailwind with custom directives in tailwind.config.js:

// tailwind.config.js
module.exports = {
    corePlugins: {
        extend: {
            'tailwind-extra': {
                'custom-shadow': '0 4px 6px -1px rgba(0, 0, 0, 0.1)',
                'gradient-custom': 'linear-gradient(90deg, #ff6b6b, #4ecdc4)',
            },
        },
    },
};

Use in Twig:

<div class="{{ tailwind('shadow-custom-shadow') }}">Custom shadow</div>
<div class="{{ tailwind('bg-gradient-custom') }}">Custom gradient</div>

Integration with Laravel Blade

Wrap Twig templates in Blade for seamless use:

// resources/views/layouts/app.blade.php
<!DOCTYPE html>
<html>
    <body>
        @include('twig::partials.header')
        @twig('content', ['data' => $data])  // Render Twig template
    </body>
</html>

Theming with Variables

Pass variables to Twig for dynamic theming:

// Controller
return view('twig::theme', [
    'theme' => 'dark',
]);

// Twig template
<div class="{{ tailwind(theme == 'dark' ? 'bg-gray-800 text-white' : 'bg-white text-black') }}">
    Themed content
</div>

Gotchas and Tips

Debugging

Class Output: Enable Twig’s debug mode to inspect merged classes:
```
// config/twig-tailwind-extra.php
'debug' => env('APP_DEBUG', false),
```
Outputs raw Tailwind classes for verification.
Merge Conflicts: Use tailwind-merge-php v0.3’s improved conflict resolution. Test edge cases like:
```
{{ tailwind('p-4 p-6') }}  {# Resolves to `p-6` #}
```

Configuration Quirks

Path to tailwind.config.js: Ensure the path in config/twig-tailwind-extra.php is correct. Default assumes the file is in the project root.
JIT Mode: If using Tailwind’s JIT compiler, ensure the package’s config aligns with your tailwind.config.js setup.

Extension Points

Custom Functions: Extend the Twig environment to add more Tailwind utilities:

// app/Providers/AppServiceProvider.php
public function boot()
{
    $twig = app('twig');
    $twig->addFunction(new \Twig\TwigFunction('tailwindGradient', [$this, 'generateGradient']));
}

public function generateGradient($from, $to)
{
    return "bg-gradient-to-r from-{$from} to-{$to}";
}

Usage in Twig:

<div class="{{ tailwindGradient('blue-500', 'purple-500') }}">Gradient</div>

Performance

Avoid Overuse: Dynamic class generation adds runtime overhead. Prefer static classes in production builds.
Lazy Loading: Use the lazy option to defer class generation:
```
{{ tailwind('bg-blue-500', { 'lazy': true }) }}
```

Common Pitfalls

Missing Dependencies: Ensure tales-from-a-dev/twig-tailwind-extra and tales-from-a-dev/tailwind-merge-php are compatible (v0.3+).
CSS Conflicts: Tailwind’s JIT mode may generate unexpected classes. Use safelist in tailwind.config.js for critical classes.

New in v1.2.0

Tailwind Merge v0.3: Improved class merging logic. Test conflicting classes (e.g., p-4 p-6) to verify resolution.
No Breaking Changes: The upgrade is backward-compatible, but edge cases in class merging may behave differently. Review your templates for unintended overrides.

Twig Tailwind Extra Laravel Package