Aller au contenu

Compatibilité et mise à niveau

Afficher au format Markdown Modifier sur GitHub Documentation de 3843abd

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.

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) : 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). 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() 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 #8
CLI --optimize Minifie, comme --minify #9
Options longues CLI --input file.css (séparé par un espace) est ignoré ; utilisez --input=file.css ou -i file.css #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
Mixins @apply @apply --my-mixin; est supprimé au lieu d’être transmis #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

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 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.