# Compatibilità e aggiornamenti

Questa pagina raccoglie le informazioni da conoscere prima di aggiornare o fare affidamento su un output esatto: i requisiti di runtime, le versioni di TailwindCSS seguite dal port, le differenze intenzionali di TailwindPHP rispetto a TailwindCSS e le note per ogni versione. La cronologia completa è in [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## Requisiti

- **PHP 8.2 o versioni successive.** La suite di test viene eseguita su PHP 8.2, 8.3 e 8.4.
- **Le estensioni `ctype` e `mbstring`.** Il compilatore chiama `ctype_*` e `mb_chr()`. Entrambe sono incluse nella maggior parte delle build di PHP e nelle immagini ufficiali Docker, ma `composer.json` non le dichiara ancora ([#11](https://github.com/inline0/tailwindphp/issues/11)), quindi una build che ne è priva installa il pacchetto ma poi fallisce durante l'esecuzione.
- **Facoltativo: `pcntl`** consente alla modalità `--watch` di CLI di arrestarsi correttamente su `SIGINT`/`SIGTERM`. Senza, la modalità di monitoraggio funziona comunque.

Non sono necessari Node.js, FFI o binari nativi.

## Quale versione di TailwindCSS viene seguita

La versione 1.7.0 segue **TailwindCSS v4.3.3**. Il repository upstream è bloccato come sottomodulo git in `reference/tailwindcss`; le suite di test vengono estratte da quel checkout bloccato e i test 4,427 vengono eseguiti a ogni push (vedere [Prestazioni e test](https://tailwindphp.inline0.dev/it/docs/advanced/performance)). I plugin portati seguono `@tailwindcss/typography` e `@tailwindcss/forms`, mentre le utility per le classi seguono clsx, tailwind-merge e CVA, tutti bloccati allo stesso modo.

## Differenze note rispetto a TailwindCSS

### Dettagli di serializzazione

CSS generato corrisponde alle suite di test di riferimento. Alcuni dettagli di serializzazione differiscono da quanto prodotto da TailwindCSS CLI, senza modificare la cascata:

- Prefissi vendor: quando il riferimento emette sia la riga `-webkit-*` originale sia una generata, TailwindPHP emette una sola riga.
- Gli pseudo-elementi trasformati per le versioni precedenti (`::file-selector-button`, `::-webkit-datetime-edit-*`) restano negli elenchi di selettori originali invece di essere separati in una regola per pseudo-elemento.
- Le stringhe originali tra apici singoli restano tali (`'Segoe UI'`) invece di essere normalizzate con doppi apici.
- Le proprietà longhand presenti insieme non vengono combinate in una proprietà shorthand (l'output di Tailwind non ne ha mai bisogno).
- `.p-0` mantiene `padding: 0px` dove il riferimento CLI emette `padding: 0`, perché il corpus di test estratto fissa la forma `0px`. Il minificatore la accorcia in `0`.

### Funzionalità non incluse

TailwindPHP è un compilatore CSS. Esclude gli strumenti per l'editor dell'ecosistema Tailwind (IntelliSense, completamento automatico e ordinamento delle classi) e le source map, quindi la CLI non offre un'opzione `--map`.

### Analisi dei contenuti

`tw::generate()` e `TailwindCompiler::generate()` leggono i nomi delle classi solo dagli attributi `class` e `className`. Per i nomi delle classi contenuti in stringhe PHP o JavaScript, usate [`tw::extractCandidatesFromStrings()`](https://tailwindphp.inline0.dev/it/docs/api#twextractcandidatesfromstrings) oppure `@source inline("…")`. Le forme di percorso di `@source` vengono ignorate da API e considerate solo in parte da CLI (vedi sotto).

### Problemi noti nella versione attuale

| Area | Comportamento attuale | Problema |
|---|---|---|
| CLI `@source` | I percorsi e i pattern glob non vengono applicati; viene invece analizzata la directory del file di input e `@source not` non esclude nulla. Consultate [Cosa analizza CLI](https://tailwindphp.inline0.dev/it/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Esegue la minificazione, come `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Opzioni lunghe di CLI | `--input file.css` (separato da spazi) viene ignorato; usate `--input=file.css` o `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Varianti dei plugin | Le varianti `addVariant()`/`matchVariant()` e i modificatori degli elementi tipografici (`prose-headings:` …) vengono compilati senza il relativo selettore | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Mixins `@apply` | `@apply --my-mixin;` viene eliminato invece di essere mantenuto | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Import di riferimento | L'output è vuoto se un import di riferimento precede l'import delle utilità; `@import "tailwindcss" reference` non ha effetto | [#14](https://github.com/inline0/tailwindphp/issues/14) |

## Note sugli aggiornamenti

### 1.7.0

- **L'output cambia byte per byte** rispetto a 1.6.x, pur restando funzionalmente equivalente al riferimento TailwindCSS v4.3.3. Tra le differenze visibili:
  - Moltiplicatori di spaziatura: `p-1` emette `padding: var(--spacing)` anziché un `calc()`; un moltiplicatore di `0` emette invece una lunghezza pari a zero senza unità.
  - Le frazioni diventano percentuali: `w-1/2` emette `width: 50%`.
  - Colori: la luminosità di `oklch()`/`oklab()` viene serializzata come percentuale (`oklch(62.3% .214 259.815)`); `white` e `black` diventano rispettivamente `#fff` e `#000`.
  - Gli pseudo-elementi CSS2 vengono serializzati con un solo due punti (`:before`, `:after`, `:first-letter`, `:first-line`).
  - Le regole `@media`/`@supports`/`@container` annidate vengono appiattite sul posto, nell'ordine del sorgente, invece di essere spostate alla fine; le dichiarazioni vengono riordinate secondo l'ordine di lightningcss e le dichiarazioni duplicate con valori sovrascritti vengono rimosse.
- **Le cache basate sull'output vengono invalidate una volta.** La chiave della cache su file di `tw::generate()` non include la versione di TailwindPHP, quindi dopo l'aggiornamento eseguite `tw::clearCache()` (o svuotate la directory passata come `cache`). La [cache dello stato del compilatore](https://tailwindphp.inline0.dev/it/docs/advanced/caching#compiler-state-cache) si invalida automaticamente.
- **Novità:** `@variant` nel CSS dell'autore, mixins CSS in `@apply`, `@media reference` e `@import "…" reference`, il motore completo `--value()`/`--modifier()` per `@utility` funzionali, convalida più rigorosa dei nomi `@utility` e l'opzione `polyfills` di `tw::compile()`.

### 1.6.1

- **Novità:** l'utilità `container` (`width: 100%` più un `max-width` per ogni punto di interruzione).
- Le variabili `--tw-*` composte (translate, scale, rotate, skew, filtri e altre) sono ora registrate con `@property`, così i fogli di stile acquisiscono queste regole `@property` e trasformazioni come `translate-x-7` hanno effetto nel browser.

### 1.6.0

- **Novità:** la cache persistente dello stato del compilatore (`stateCacheFile` su `tw::compile()` e `TailwindCompiler`, `StateCache\compileCssCached()`) e le funzioni separate `parseCssState()`/`finalizeCssState()`/`compileParsed()`. Le chiamate esistenti si comportano esattamente come prima.

### 1.5.0

- Le sottoclassi di `TailwindCompiler` che sovrascrivono `generate()` o `css()` devono aggiungere il parametro facoltativo `bool $minify = false`; PHP rifiuta le sovrascritture che omettono un parametro facoltativo della classe genitore.
- L'output minificato proviene dal serializzatore, quindi differisce leggermente byte per byte da 1.4.x (le cache basate sull'output minificato vengono invalidate una volta).
- **Novità:** `generateExact()` e `cssExact()` per CSS separati per pagina da un unico compilatore a lunga durata.