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 et 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.

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 :

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.

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().

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.

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.

use function TailwindPHP\join;

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

Laquelle choisir ?

Imports

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).