# Prestazioni e test

TailwindPHP dà la priorità alla correttezza. Quando una modifica specifica di PHP migliora le prestazioni senza alterare l'output, viene applicata e contrassegnata con `@port-deviation:performance`. La parità con TailwindCSS non viene data per scontata: viene verificata continuamente con la suite di test di Tailwind.

## Prestazioni

Il port PHP privilegia la corrispondenza dell'output di TailwindCSS rispetto alla velocità pura; l'originale TypeScript resta comunque più veloce: il JIT di V8 compila i percorsi più usati in codice nativo, cosa che PHP non può eguagliare. Per generare CSS a ogni richiesta o pagina, riutilizzate un compilatore (vedi [generateExact()](https://tailwindphp.inline0.dev/it/docs/api#accumulating-vs-exact-generation)) e salvate il suo stato di costruzione con [`stateCacheFile`](https://tailwindphp.inline0.dev/it/docs/advanced/caching#compiler-state-cache).

Alcuni percorsi più usati includono ottimizzazioni messe a punto manualmente che **mantengono invariato l'output**:

- **`ast.php` `toCss()`** — accumula i frammenti in un array e li `implode` una volta sola, invece di concatenare ripetutamente le stringhe; usa inoltre stringhe di indentazione precalcolate.
- **`css-parser.php`** — confronta direttamente i caratteri invece di passare da `ord()` e tiene traccia delle lunghezze dei buffer invece di ricalcolare `strlen()`.

Entrambe sono documentate con `@port-deviation:performance` e vincolate alla suite di test: non possono modificare l'CSS generato.

### Benchmark

La directory `benchmarks/` contiene uno strumento di confronto. Eseguitelo con:

```bash
composer bench         # PHP vs TypeScript
composer bench:save    # write benchmarks/results.json
```

Risultati esemplificativi su PHP 8.4.5 / Node.js v22.17.0 (Apple M1):

| Benchmark | PHP | TypeScript |
|-----------|-----|------------|
| `css-parser` su preflight.css | ~816 ops/s | ~15.45K ops/s (≈20× più veloce) |
| `toCss` | ~65.85K ops/s | ~2.59M ops/s (≈39× più veloce) |

TypeScript è più veloce in queste operazioni di basso livello, come previsto. Per generare CSS di pagine complete, il caso d'uso effettivo, le prestazioni di PHP sono adeguate (circa 14 ms per pagina nell'esecuzione di esempio). Con input identici ripetuti, la [cache su file](https://tailwindphp.inline0.dev/it/docs/advanced/caching) elimina del tutto il costo.

## Test e parità

I test garantiscono che il port PHP produca lo stesso output di TailwindCSS. Si usano insieme due approcci.

**1. Test basati sull'estrazione.** Gli script in `test-coverage/` analizzano i file `.test.ts` di TailwindCSS ed estraggono i casi di test in JSON. PHPUnit li esegue poi tramite TailwindPHP e confronta l'output con il valore atteso CSS. Poiché le aspettative provengono direttamente dal progetto upstream, ogni divergenza nel comportamento di PHP viene rilevata come errore. Questi test coprono gli aspetti più complessi: utility, varianti, integrazione, funzioni CSS e test a livello di browser `ui.spec`.

**2. Test unitari portati manualmente.** I file di test TypeScript più semplici (AST, parsing di CSS, escaping, parsing dei candidati, parsing dei valori, …) vengono portati direttamente in PHP e collocati accanto al relativo sorgente come `*.test.php`, riproducendo la struttura e le verifiche degli originali.

Il ciclo è **estrai → esegui → verifica**: riestraete i test dal riferimento TailwindCSS attuale, eseguite la suite e ogni divergenza viene segnalata come errore. In questo modo il port resta sincronizzato con upstream e un aggiornamento di TailwindCSS può essere verificato automaticamente, senza controlli manuali. Le divergenze interrompono CI.

```bash
composer extract   # re-extract test cases from the TailwindCSS reference
composer test      # run the full suite
```

Alla release 1.7.0 (riferimento TailwindCSS v4.3.3), i test superati sono **4,427**:

| Suite | Test | Origine |
|-------|-------|--------|
| Suite TailwindCSS estratte (utility 706, varianti 164, index 148, css-functions 64, `ui.spec` 68) | 1,150 | estratte da `.test.ts` / `.spec.ts` |
| Copertura API (utility, modificatori, varianti, direttive, plugin, importazioni, `@source`, cache, API pubblico) | 2,252 | `tests/` |
| Test unitari accanto ai sorgenti (parser, AST, candidati, tema, utility, parser dei selettori, trasformazioni lightningcss, minimizzatore) | 767 | port di `*.test.php` e test specifici di PHP |
| CLI (parsing degli argomenti, output, build) | 84 | `tests/Cli*Test.php` |
| Port dei plugin (tipografia, moduli) | 45 | `*.test.php` accanto ai plugin |
| Librerie complementari (clsx, tailwind-merge, CVA) | 129 | suite di riferimento |

## Qualità del codice

La formattazione e l'analisi statica vengono eseguite tramite gli script di Composer:

```bash
composer lint      # Pint --test  (check formatting)
composer format    # Pint         (fix formatting)
composer analyse   # PHPStan      (static analysis, level 4)
composer quality   # lint + analyse
```

PHPStan viene eseguito al livello 4 (`phpstan.neon`), con un breve elenco di pattern ignorati per le forme dinamiche degli array usate dall'architettura basata su funzioni. Vengono analizzati tutti i file sorgente; quelli di test sono esclusi.

Per la struttura verificata da questi test e per le deviazioni registrate, vedi [Architettura](https://tailwindphp.inline0.dev/it/docs/advanced/architecture).