Utilitários de classes

Criar atributos class em templates significa combinar strings, alternar classes conforme condições e impedir que utilitários posteriores entrem em conflito com os anteriores (p-2 e p-4 não devem coexistir). Em JavaScript, esse trabalho é dividido entre clsx e tailwind-merge. TailwindPHP inclui PHP implementações de ambos, para que você tenha o mesmo comportamento sem cadeia de ferramentas Node.js e sem pacotes Composer adicionais.

Três funções cobrem todos os casos: cn() cria e resolve conflitos, merge() apenas resolve conflitos e join() apenas concatena.

cn()

O utilitário recomendado. Primeiro, executa a criação condicional no estilo clsx e, em seguida, resolve conflitos Tailwind com tailwind-merge — assim, o último utilitário conflitante prevalece.

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'

Argumentos aceitos

cn() aceita qualquer número de argumentos. Cada um é nivelado e filtrado seguindo a semântica de clsx:

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

Padrão de componente

cn() permite sobrescrever um componente: combine as classes do próprio componente com as fornecidas por quem o chama, e os conflitos serão resolvidos a favor de quem o chama.

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>

Para estilos declarativos de componentes com múltiplos eixos, combine cn() com variants().

merge()

Apenas resolução de conflitos — sem criação condicional. Passe strings de classe; as classes posteriores sobrescrevem as anteriores quando visam a mesma propriedade. Use quando sua entrada já consistir em strings 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() é merge() construído sobre clsx; portanto, use merge() diretamente apenas quando não precisar da sintaxe condicional de arrays.

join()

Concatenação simples, sem resolução de conflitos. Valores falsos são descartados, mas todos os utilitários conflitantes são mantidos. Use quando souber que não há conflitos e quiser a opção mais econômica.

use function TailwindPHP\join;

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

Qual devo usar?

Importações

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

As três ficam no namespace principal TailwindPHP e são incluídas no pacote. São implementações PHP de clsx (de Luke Edwards) e tailwind-merge (de Dany Castillo).