Pular para o conteúdo

Compatibilidade e atualização

Ver como Markdown Editar no GitHub Documentação em 3843abd

Esta página reúne o que você precisa saber antes de atualizar ou depender de uma saída exata: os requisitos de execução, qual versão TailwindCSS a adaptação acompanha, em que pontos TailwindPHP difere intencionalmente de TailwindCSS e as notas de cada versão. O histórico completo está em CHANGELOG.md.

Requisitos

  • PHP 8.2 ou posterior. O conjunto de testes é executado em PHP 8.2, 8.3 e 8.4.
  • As extensões ctype e mbstring. O compilador chama ctype_* e mb_chr(). Ambas acompanham a maioria das compilações de PHP e as imagens oficiais de Docker, mas composer.json ainda não as declara (#11), então uma compilação sem elas instala o pacote, mas falha em tempo de execução.
  • Opcional: pcntl permite que o modo --watch de CLI pare corretamente em SIGINT/SIGTERM. Sem isso, o modo de observação continua funcionando.

Não há Node.js, FFI nem binários nativos envolvidos.

Qual versão de TailwindCSS é acompanhada

A versão 1.7.0 acompanha TailwindCSS v4.3.3. O repositório upstream é fixado como um submódulo git em reference/tailwindcss; seus conjuntos de testes são extraídos desse checkout fixado, e os testes de 4,427 são executados a cada push (consulte Desempenho e testes). Os plugins adaptados acompanham @tailwindcss/typography e @tailwindcss/forms, e os utilitários de classes acompanham clsx, tailwind-merge e CVA, todos fixados da mesma forma.

Diferenças conhecidas em relação a TailwindCSS

Detalhes da serialização

O CSS gerado corresponde aos conjuntos de testes de referência. Alguns detalhes da serialização diferem do que o TailwindCSS CLI imprime, mas nenhum deles altera a cascata:

  • Prefixos de fornecedores: quando a referência emite tanto a linha -webkit-* escrita pelo autor quanto uma linha gerada, TailwindPHP emite uma só linha.
  • Elementos pseudo reduzidos para versões anteriores (::file-selector-button, ::-webkit-datetime-edit-*) permanecem em suas listas de seletores originais, em vez de serem divididos em uma regra por elemento pseudo.
  • Strings originais entre aspas simples permanecem assim ('Segoe UI'), em vez de serem normalizadas para aspas duplas.
  • Propriedades longhand que ocorrem juntas não são combinadas em uma propriedade abreviada (a própria saída de Tailwind nunca precisa disso).
  • .p-0 mantém padding: 0px, enquanto a referência CLI emite padding: 0, porque o corpus de testes extraído fixa o formato 0px. O minificador o reduz para 0.

O que não está incluído

TailwindPHP é um compilador CSS. Ele não inclui as ferramentas de edição do ecossistema Tailwind (IntelliSense, preenchimento automático, ordenação de classes) nem source maps; por isso, a CLI não tem uma opção --map.

Leitura de conteúdo

tw::generate() e TailwindCompiler::generate() leem nomes de classes apenas de atributos class e className. Para nomes de classes contidos em strings PHP ou JavaScript, use tw::extractCandidatesFromStrings() ou @source inline("…"). O API ignora os formatos de caminho de @source e o CLI só os reconhece parcialmente (veja abaixo).

Problemas conhecidos na versão atual

Área Comportamento atual Problema
CLI @source Caminhos e padrões glob não são aplicados; o diretório do arquivo de entrada é analisado, e @source not não exclui nada. Consulte O que o CLI analisa #8
CLI --optimize Minifica, assim como --minify #9
Opções longas de CLI --input file.css (separado por espaços) é ignorado; use --input=file.css ou -i file.css #13
Variantes de plugin As variantes addVariant()/matchVariant() e os modificadores de elementos de tipografia (prose-headings: …) são compilados sem o seletor #10
Mixins @apply @apply --my-mixin; é descartado em vez de ser mantido #12
Importações de referência A saída fica vazia quando uma importação de referência vem antes da importação de utilitários; @import "tailwindcss" reference não tem efeito #14

Notas de atualização

1.7.0

  • A saída muda byte a byte em comparação com 1.6.x, embora continue funcionalmente equivalente à referência de TailwindCSS v4.3.3. Entre as mudanças visíveis:
    • Multiplicadores de espaçamento: p-1 emite padding: var(--spacing) em vez de um calc(), e um multiplicador de 0 emite um comprimento zero simples.
    • Frações são convertidas em porcentagens: w-1/2 emite width: 50%.
    • Cores: a luminosidade de oklch()/oklab() é serializada como porcentagem (oklch(62.3% .214 259.815)); white e black são reduzidos para #fff e #000.
    • Os elementos pseudo do CSS2 são serializados com dois-pontos simples (:before, :after, :first-letter, :first-line).
    • Regras @media/@supports/@container aninhadas são achatadas no lugar, na ordem do código-fonte, em vez de serem movidas para o fim; as declarações são reordenadas conforme a ordem do lightningcss; declarações duplicadas sobrescritas são removidas.
  • Os caches baseados na saída são invalidados uma vez. A chave do cache de arquivos de tw::generate() não inclui a versão de TailwindPHP, então execute tw::clearCache() (ou o diretório passado como cache) depois de atualizar. O cache do estado do compilador é invalidado automaticamente.
  • Novidades: @variant em CSS original, mixins CSS em @apply, @media reference e @import "…" reference, o mecanismo completo de --value()/--modifier() para @utility funcional, validação mais rigorosa dos nomes de @utility e a opção polyfills de tw::compile().

1.6.1

  • Novidade: o utilitário container (width: 100% mais um max-width por ponto de interrupção).
  • Variáveis --tw-* compostas (translação, escala, rotação, inclinação, filtros e outras) agora são registradas em @property, então as folhas de estilo recebem essas regras @property, e transformações como translate-x-7 passam a funcionar no navegador.

1.6.0

  • Novidade: o cache persistente do estado do compilador (stateCacheFile em tw::compile() e TailwindCompiler, StateCache\compileCssCached()) e as funções parseCssState()/finalizeCssState()/compileParsed() separadas. As chamadas existentes continuam funcionando exatamente como antes.

1.5.0

  • Subclasses de TailwindCompiler que substituem generate() ou css() precisam adicionar o parâmetro opcional bool $minify = false; PHP rejeita substituições que omitem um parâmetro opcional da classe pai.
  • A saída minificada vem do serializador, então os bytes minificados diferem ligeiramente de 1.4.x (os caches baseados na saída minificada são invalidados uma vez).
  • Novidade: generateExact() e cssExact() para CSS por página usando um compilador de longa duração.