# Performances et tests

TailwindPHP privilégie d'abord la conformité. Lorsqu'une modification propre à PHP accélère le traitement sans altérer la sortie, elle est appliquée et signalée par `@port-deviation:performance`. La parité avec TailwindCSS n'est pas présumée : elle est vérifiée en continu à l'aide de la suite de tests de Tailwind.

## Performances

Le port PHP privilégie la conformité à la sortie de TailwindCSS plutôt que le débit brut, et l'original en TypeScript reste de toute façon plus rapide : le JIT de V8 compile les chemins critiques en code natif, ce que PHP ne peut égaler. Pour le CSS généré à chaque requête ou page, réutilisez un compilateur (voir [generateExact()](https://tailwindphp.inline0.dev/fr/docs/api#accumulating-vs-exact-generation)) et conservez son état de construction avec [`stateCacheFile`](https://tailwindphp.inline0.dev/fr/docs/advanced/caching#compiler-state-cache).

Quelques chemins critiques bénéficient d'optimisations réglées à la main qui **préservent une sortie identique** :

- **`ast.php` `toCss()`** — accumule les fragments dans un tableau et les `implode` en une seule fois au lieu de concaténer les chaînes à répétition, et utilise des chaînes d'indentation précalculées.
- **`css-parser.php`** — compare directement les caractères au lieu de passer par `ord()`, et suit la longueur des tampons au lieu de recalculer `strlen()`.

Les deux sont documentées avec `@port-deviation:performance` et soumises à la suite de tests : elles ne peuvent pas modifier le CSS généré.

### Benchmarks

Le répertoire `benchmarks/` contient un banc d'essai comparatif. Lancez-le avec :

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

Résultats indicatifs sur PHP 8.4.5 / Node.js v22.17.0 (Apple M1) :

| Benchmark | PHP | TypeScript |
|-----------|-----|------------|
| `css-parser` sur preflight.css | ~816 ops/s | ~15.45K ops/s (≈20× plus rapide) |
| `toCss` | ~65.85K ops/s | ~2.59M ops/s (≈39× plus rapide) |

TypeScript est plus rapide pour ces opérations de bas niveau, comme prévu. Pour générer une page entière de CSS — le cas d'usage réel —, les performances de PHP sont suffisantes (environ 14 ms par page lors de l'exécution d'exemple). Pour une même entrée répétée, le [cache de fichiers](https://tailwindphp.inline0.dev/fr/docs/advanced/caching) élimine entièrement ce coût.

## Tests et parité

Les tests garantissent que le port PHP produit la même sortie que TailwindCSS. Deux approches se complètent.

**1. Tests fondés sur l'extraction.** Les scripts dans `test-coverage/` analysent les fichiers `.test.ts` de TailwindCSS et en extraient les cas de test dans JSON. PHPUnit exécute ensuite ces cas avec TailwindPHP et compare la sortie à la valeur CSS attendue. Comme les attentes proviennent directement du projet d'origine, tout écart de comportement de PHP entraîne un échec. Ces tests couvrent les cas complexes : utilitaires, variantes, intégration, fonctions CSS et tests `ui.spec` dans le navigateur.

**2. Tests unitaires portés à la main.** Les fichiers de test TypeScript plus simples (AST, analyse de CSS, échappement, analyse des candidats et des valeurs, …) sont portés directement vers PHP et placés à côté de leur source sous forme de `*.test.php`, en reprenant la structure et les assertions des originaux.

La boucle suit les étapes **extraire → exécuter → vérifier** : réextrayez les tests depuis la référence TailwindCSS actuelle, puis lancez la suite ; tout écart entraîne un échec. Le port reste ainsi en phase avec le projet d'origine et une mise à jour de TailwindCSS peut être validée automatiquement plutôt que par inspection. Tout écart fait échouer l'intégration continue.

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

La version 1.7.0 (référence TailwindCSS v4.3.3) compte **4,427 tests réussis** :

| Suite | Tests | Source |
|-------|-------|--------|
| Suites TailwindCSS extraites (utilitaires 706, variantes 164, index 148, css-functions 64, `ui.spec` 68) | 1,150 | extraits de `.test.ts` / `.spec.ts` |
| Couverture de API (utilitaires, modificateurs, variantes, directives, plugins, imports, `@source`, mise en cache, API publique) | 2,252 | `tests/` |
| Tests unitaires près du code source (analyseur, AST, candidats, thème, utilitaires, analyseur de sélecteurs, transformations lightningcss, minificateur) | 767 | ports de `*.test.php` et tests propres à PHP |
| CLI (analyse des arguments, sortie, compilations) | 84 | `tests/Cli*Test.php` |
| Ports des plugins (typographie, formulaires) | 45 | `*.test.php`, à côté des plugins |
| Bibliothèques associées (clsx, tailwind-merge, CVA) | 129 | suites de référence |

## Qualité du code

Le formatage et l'analyse statique sont exécutés par les scripts 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 s'exécute au niveau 4 (`phpstan.neon`), avec une courte liste de motifs ignorés pour les formes de tableaux dynamiques utilisées par l'architecture fondée sur les fonctions. Tous les fichiers source sont analysés, les fichiers de test sont exclus.

Pour connaître la structure vérifiée par ces tests et les écarts consignés, consultez [Architecture](https://tailwindphp.inline0.dev/fr/docs/advanced/architecture).