# Compatibilité et mise à niveau

Cette page rassemble les informations à connaître avant une mise à niveau ou si vous avez besoin d’une sortie exacte : les prérequis d’exécution, la version de TailwindCSS suivie par le portage, les différences assumées de TailwindPHP par rapport à TailwindCSS et les notes de chaque version. L’historique complet se trouve dans [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## Prérequis

- **PHP 8.2 ou version ultérieure.** La suite de tests s’exécute sur PHP 8.2, 8.3 et 8.4.
- **Les extensions `ctype` et `mbstring`.** Le compilateur appelle `ctype_*` et `mb_chr()`. Elles sont toutes deux fournies avec la plupart des versions PHP et les images officielles Docker, mais `composer.json` ne les déclare pas encore ([#11](https://github.com/inline0/tailwindphp/issues/11)) : une compilation sans elles installe le paquet, puis échoue à l’exécution.
- **Facultatif : `pcntl`** permet au mode `--watch` de CLI de s’arrêter proprement sur `SIGINT`/`SIGTERM`. Sans cette extension, le mode de surveillance fonctionne toujours.

Aucun Node.js, aucune FFI et aucun binaire natif ne sont utilisés.

## Version TailwindCSS suivie

La version 1.7.0 suit **TailwindCSS v4.3.3**. Le dépôt amont est épinglé comme sous-module git dans `reference/tailwindcss` ; ses suites de tests sont extraites de cette copie épinglée, et les tests 4,427 s’exécutent à chaque push (voir [Performances et tests](https://tailwindphp.inline0.dev/fr/docs/advanced/performance)). Les plugins portés suivent `@tailwindcss/typography` et `@tailwindcss/forms`, et les utilitaires de classes suivent clsx, tailwind-merge et CVA, chacun épinglé de la même manière.

## Différences connues avec TailwindCSS

### Détails de sérialisation

Le CSS généré correspond aux suites de tests de référence. Quelques détails de sérialisation diffèrent de ce qu’affiche TailwindCSS CLI, sans modifier la cascade :

- Préfixes vendeurs : lorsque la référence émet à la fois la ligne `-webkit-*` écrite par l’auteur et une ligne générée, TailwindPHP n’en émet qu’une.
- Les pseudo-éléments rétrogradés (`::file-selector-button`, `::-webkit-datetime-edit-*`) restent dans leurs listes de sélecteurs d’origine au lieu d’être séparés en une règle par pseudo-élément.
- Les chaînes écrites avec des apostrophes simples restent ainsi (`'Segoe UI'`), au lieu d’être normalisées avec des guillemets doubles.
- Les propriétés longues présentes ensemble ne sont pas combinées en propriété abrégée (la sortie de Tailwind n’en a jamais besoin).
- `.p-0` conserve `padding: 0px` là où la référence CLI émet `padding: 0`, car le corpus de tests extrait impose la forme `0px`. Le minificateur la raccourcit en `0`.

### Éléments non inclus

TailwindPHP est un compilateur CSS. Il n’inclut pas les outils d’édition de l’écosystème Tailwind (IntelliSense, autocomplétion, tri des classes) ni les source maps ; le CLI ne propose donc pas d’option `--map`.

### Analyse du contenu

`tw::generate()` et `TailwindCompiler::generate()` lisent les noms de classe uniquement dans les attributs `class` et `className`. Pour les noms de classe présents dans des chaînes PHP ou JavaScript, utilisez [`tw::extractCandidatesFromStrings()`](https://tailwindphp.inline0.dev/fr/docs/api#twextractcandidatesfromstrings) ou `@source inline("…")`. Les formes de chemin de `@source` sont ignorées par API et seulement partiellement prises en charge par CLI (voir ci-dessous).

### Problèmes connus dans la version actuelle

| Domaine | Comportement actuel | Problème |
|---|---|---|
| CLI `@source` | Les chemins et les motifs glob ne sont pas appliqués ; le répertoire du fichier d’entrée est analysé à la place, et `@source not` n’exclut rien. Voir [Ce que l’analyseur CLI analyse](https://tailwindphp.inline0.dev/fr/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Minifie, comme `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Options longues CLI | `--input file.css` (séparé par un espace) est ignoré ; utilisez `--input=file.css` ou `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Variantes de greffons | Les variantes `addVariant()`/`matchVariant()` et les modificateurs d’élément de typographie (`prose-headings:` …) sont compilés sans leur sélecteur | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Mixins `@apply` | `@apply --my-mixin;` est supprimé au lieu d’être transmis | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Imports de référence | La sortie est vide si un import de référence précède l’import des utilitaires ; `@import "tailwindcss" reference` n’a aucun effet | [#14](https://github.com/inline0/tailwindphp/issues/14) |

## Notes de mise à niveau

### 1.7.0

- **La sortie change octet par octet** par rapport à 1.6.x, tout en restant fonctionnellement équivalente à la référence TailwindCSS v4.3.3. Parmi les changements visibles :
  - Multiplicateurs d’espacement : `p-1` émet `padding: var(--spacing)` au lieu d’un `calc()`, et un multiplicateur de `0` émet une longueur nulle sans unité.
  - Les fractions sont converties en pourcentages : `w-1/2` émet `width: 50%`.
  - Couleurs : la luminosité de `oklch()`/`oklab()` est sérialisée en pourcentage (`oklch(62.3% .214 259.815)`), `white` et `black` sont raccourcis en `#fff` et `#000`.
  - Les pseudo-éléments CSS2 sont sérialisés avec un seul deux-points (`:before`, `:after`, `:first-letter`, `:first-line`).
  - Les règles `@media`/`@supports`/`@container` imbriquées sont aplaties sur place, dans l’ordre source, au lieu d’être déplacées à la fin ; les déclarations sont réordonnées comme le fait lightningcss et les déclarations en doublon masquées sont supprimées.
- **Les caches basés sur la sortie sont invalidés une fois.** La clé du cache de fichiers de `tw::generate()` n’inclut pas la version de TailwindPHP ; exécutez donc `tw::clearCache()` (ou le répertoire indiqué à `cache`) après la mise à niveau. Le [cache de l’état du compilateur](https://tailwindphp.inline0.dev/fr/docs/advanced/caching#compiler-state-cache) s’invalide automatiquement.
- **Nouveau :** `@variant` dans le CSS de l’auteur, les mixins CSS dans `@apply`, `@media reference` et `@import "…" reference`, le moteur complet `--value()`/`--modifier()` pour `@utility` fonctionnel, une validation plus stricte des noms `@utility` et l’option `polyfills` de `tw::compile()`.

### 1.6.1

- **Nouveau :** l’utilitaire `container` (`width: 100%` plus un `max-width` par point de rupture).
- Les variables `--tw-*` composées (translation, échelle, rotation, inclinaison, filtres et autres) sont maintenant enregistrées auprès de `@property` ; les feuilles de style gagnent donc ces règles `@property` et les transformations telles que `translate-x-7` prennent effet dans le navigateur.

### 1.6.0

- **Nouveau :** le cache persistant de l’état du compilateur (`stateCacheFile` sur `tw::compile()` et `TailwindCompiler`, `StateCache\compileCssCached()`), ainsi que la séparation des fonctions `parseCssState()`/`finalizeCssState()`/`compileParsed()`. Les appels existants se comportent exactement comme avant.

### 1.5.0

- Les sous-classes de `TailwindCompiler` qui redéfinissent `generate()` ou `css()` doivent ajouter le paramètre facultatif `bool $minify = false` ; PHP rejette les redéfinitions qui omettent un paramètre facultatif de la classe parente.
- La sortie minifiée provient du sérialiseur ; ses octets diffèrent donc légèrement de 1.4.x (les caches basés sur la sortie minifiée sont invalidés une fois).
- **Nouveau :** `generateExact()` et `cssExact()` pour obtenir un CSS par page à partir d’un compilateur de longue durée.