# Utilitaires de classes

Construire des attributs `class` dans des templates implique de concaténer des chaînes, d'activer ou désactiver des classes selon certaines conditions et d'empêcher les utilitaires suivants d'entrer en conflit avec les précédents (`p-2` et `p-4` ne doivent pas coexister). Dans JavaScript, ce travail est réparti entre [clsx](https://github.com/lukeed/clsx) et [tailwind-merge](https://github.com/dcastil/tailwind-merge). TailwindPHP fournit des ports PHP des deux, pour obtenir le même comportement sans chaîne d'outils Node.js ni packages supplémentaires Composer.

Trois fonctions couvrent tous les besoins : `cn()` construit et résout les conflits, `merge()` résout uniquement les conflits et `join()` concatène uniquement.

## cn()

L'utilitaire recommandé. Il construit d'abord les classes de façon conditionnelle, comme clsx, puis résout les conflits Tailwind avec tailwind-merge : en cas de conflit, le dernier utilitaire l'emporte.

```php
use function TailwindPHP\cn;

// Conflicts are resolved — px-4 overrides px-2
cn('px-2 py-1', 'px-4');
// => 'py-1 px-4'

// Conditional classes via a key => bool array
cn('btn', ['btn-primary' => true, 'btn-disabled' => false]);
// => 'btn btn-primary'
```

### Arguments acceptés

`cn()` accepte un nombre quelconque d'arguments. Chacun est aplati et filtré selon la sémantique de clsx :

| Argument | Comportement |
|----------|----------|
| `string` | Ajouté tel quel. |
| `int` / `float` | Converti en chaîne, puis ajouté. |
| Tableau imbriqué | Chaque élément est traité récursivement. |
| Tableau `key => bool` | Chaque clé est ajoutée si sa valeur est véridique. |
| `null`, `false`, `0`, `''` | Ignorés. |

```php
cn('flex', ['items-center' => true], ['p-4', ['gap-2']], null);
// => 'flex items-center p-4 gap-2'
```

### Modèle de composant

`cn()` permet de remplacer les classes d'un composant : fusionnez ses propres classes avec celles fournies par l'appelant, et les conflits sont résolus en faveur de ce dernier.

```php
use function TailwindPHP\cn;

function Card(array $props = []): string {
    $class = cn(
        'rounded-lg border bg-card text-card-foreground shadow-sm',
        $props['class'] ?? null
    );
    return "<div class=\"{$class}\">" . ($props['children'] ?? '') . "</div>";
}

Card(['class' => 'p-6', 'children' => 'Content']);
// <div class="rounded-lg border bg-card text-card-foreground shadow-sm p-6">Content</div>
```

Pour des styles de composants déclaratifs à plusieurs axes, associez `cn()` à [variants()](https://tailwindphp.inline0.dev/fr/docs/class-utilities/variants).

## merge()

Résolution des conflits uniquement — sans construction conditionnelle. Passez des chaînes de classes ; les classes suivantes remplacent les précédentes lorsqu'elles ciblent la même propriété. À utiliser lorsque votre entrée est déjà composée de chaînes simples.

```php
use function TailwindPHP\merge;

merge('px-2 py-1 bg-red-500', 'px-4 bg-blue-500');
// => 'py-1 px-4 bg-blue-500'

// Conflict resolution is variant-aware
merge('hover:bg-red-500', 'hover:bg-blue-500');
// => 'hover:bg-blue-500'
```

`cn()` est `merge()` construit par-dessus clsx ; utilisez donc directement `merge()` uniquement si vous n'avez pas besoin de la syntaxe des tableaux conditionnels.

## join()

Concaténation simple, sans résolution des conflits. Les valeurs fausses sont supprimées, mais tous les utilitaires en conflit sont conservés. À utiliser lorsque vous savez qu'il n'y a aucun conflit et recherchez l'option la plus légère.

```php
use function TailwindPHP\join;

join('foo', 'bar', null, 'baz');
// => 'foo bar baz'
```

## Laquelle choisir ?

| Fonction | Construit (conditions, tableaux) | Résout les conflits | À utiliser lorsque |
|----------|:---:|:---:|----------|
| `cn()`    | oui | oui | Choix par défaut : pour créer des chaînes de classes susceptibles d'entrer en conflit. |
| `merge()` | non  | oui | L'entrée est composée de chaînes simples et vous avez uniquement besoin de résoudre les conflits. |
| `join()`  | oui | non  | Vous savez qu'il n'y a aucun conflit et souhaitez réduire le travail au minimum. |

## Imports

```php
use function TailwindPHP\cn;
use function TailwindPHP\merge;
use function TailwindPHP\join;
```

Les trois se trouvent dans l'espace de noms principal `TailwindPHP` et sont inclus avec le package. Ce sont des ports PHP de clsx (par Luke Edwards) et de tailwind-merge (par Dany Castillo).