# Compatibilidade e atualização

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](https://github.com/inline0/tailwindphp/blob/main/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](https://github.com/inline0/tailwindphp/issues/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](https://tailwindphp.inline0.dev/pt/docs/advanced/performance)). 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()`](https://tailwindphp.inline0.dev/pt/docs/api#twextractcandidatesfromstrings) 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](https://tailwindphp.inline0.dev/pt/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Minifica, assim como `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Opções longas de CLI | `--input file.css` (separado por espaços) é ignorado; use `--input=file.css` ou `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Variantes de plugin | As variantes `addVariant()`/`matchVariant()` e os modificadores de elementos de tipografia (`prose-headings:` …) são compilados sem o seletor | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Mixins `@apply` | `@apply --my-mixin;` é descartado em vez de ser mantido | [#12](https://github.com/inline0/tailwindphp/issues/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](https://github.com/inline0/tailwindphp/issues/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](https://tailwindphp.inline0.dev/pt/docs/advanced/caching#compiler-state-cache) é 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.