Přejít k obsahu

Kompatibilita a upgrade

Zobrazit jako Markdown Upravit na GitHub Dokumentace na 3843abd

Tato stránka shrnuje, co potřebujete vědět před upgradem nebo pokud spoléháte na přesný výstup: požadavky na běhové prostředí, které vydání TailwindCSS port sleduje, v čem se TailwindPHP záměrně liší od TailwindCSS a poznámky ke každému vydání. Úplnou historii najdete v CHANGELOG.md.

Požadavky

  • PHP 8.2 nebo novější. Testovací sada běží na PHP 8.2, 8.3 a 8.4.
  • Rozšíření ctype a mbstring. Kompilátor volá ctype_* a mb_chr(). Obě jsou součástí většiny sestavení PHP i oficiálních obrazů Docker, ale composer.json je zatím neuvádí (#11), takže při jejich absenci se balíček nainstaluje, ale za běhu selže.
  • Volitelné: pcntl umožňuje režimu --watch v CLI korektně se ukončit při SIGINT/SIGTERM. Bez něj režim sledování stále funguje.

Nepoužívá se Node.js, FFI ani nativní binární soubory.

Které vydání TailwindCSS se sleduje

Vydání 1.7.0 sleduje TailwindCSS v4.3.3. Repozitář upstreamu je připnutý jako podmodul git v reference/tailwindcss, jeho testovací sady se extrahují z připnuté kopie a testy 4,427 se spouštějí při každém pushnutí (viz Výkon a testování). Portované pluginy vycházejí z @tailwindcss/typography a @tailwindcss/forms a pomocné nástroje pro třídy z clsx, tailwind-merge a CVA; všechny jsou připnuté stejným způsobem.

Známé rozdíly oproti TailwindCSS

Podrobnosti serializace

Generované CSS odpovídá referenčním testovacím sadám. Některé podrobnosti serializace se liší od výstupu TailwindCSS CLI, žádná z nich však nemění kaskádu:

  • Předpony dodavatelů: tam, kde referenční výstup uvádí autorský řádek -webkit-* i vygenerovaný řádek, TailwindPHP uvádí pouze jeden.
  • Převedené pseudo-elementy (::file-selector-button, ::-webkit-datetime-edit-*) zůstávají v původních seznamech selektorů, místo aby se rozdělily na jedno pravidlo pro každý pseudo-element.
  • Původní řetězce v jednoduchých uvozovkách zůstávají v jednoduchých uvozovkách ('Segoe UI'), místo aby se normalizovaly na dvojité uvozovky.
  • Souběžně se vyskytující dlouhé vlastnosti se neslučují do zkráceného zápisu (vlastní výstup Tailwind jej nikdy nepotřebuje).
  • .p-0 zachovává padding: 0px tam, kde referenční CLI uvádí padding: 0, protože extrahovaný testovací korpus vyžaduje podobu 0px. Minifikátor ji zkracuje na 0.

Co není zahrnuto

TailwindPHP je kompilátor CSS. Neobsahuje nástroje editoru z ekosystému Tailwind (IntelliSense, automatické doplňování, řazení tříd) ani zdrojové mapy, takže CLI nemá možnost --map.

Skenování obsahu

tw::generate() a TailwindCompiler::generate() čtou názvy tříd pouze z atributů class a className. U názvů tříd uložených v řetězcích PHP nebo JavaScript použijte tw::extractCandidatesFromStrings() nebo @source inline("…"). Cesty v @source se ignorují v API a CLI je zohledňuje jen částečně (viz níže).

Známé problémy v aktuálním vydání

Oblast Aktuální chování Problém
CLI @source Cesty a globy se neuplatňují; místo toho se skenuje adresář vstupního souboru a @source not nic nevylučuje. Viz Co skenuje CLI #8
CLI --optimize Minifikuje stejně jako --minify #9
Dlouhé volby CLI --input file.css (oddělené mezerou) se ignoruje; použijte --input=file.css nebo -i file.css #13
Varianty pluginů Varianty addVariant()/matchVariant() a modifikátory typografických elementů (prose-headings: …) se kompilují bez selektoru #10
Mixiny @apply @apply --my-mixin; se zahodí místo předání dál #12
Referenční importy Výstup je prázdný, pokud import referencí předchází importu utilit; @import "tailwindcss" reference nemá žádný účinek #14

Poznámky k upgradu

1.7.0

  • Výstup se liší v bajtech oproti 1.6.x, ale funkčně zůstává ekvivalentní referenci TailwindCSS v4.3.3. Mezi viditelné změny patří:
    • Násobitele mezer: p-1 vypíše padding: var(--spacing) místo hodnoty calc() a násobitel 0 vypíše jako prostou nulovou délku.
    • Zlomky se převádějí na procenta: w-1/2 vypíše width: 50%.
    • Barvy: světlost oklch()/oklab() se serializuje jako procento (oklch(62.3% .214 259.815)), white a black se zkracují na #fff a #000.
    • Pseudo-elementy CSS2 se serializují s jednou dvojtečkou (:before, :after, :first-letter, :first-line).
    • Vnořená pravidla @media/@supports/@container se zplošťují na místě v pořadí zdroje, místo aby se přesunula na konec; deklarace se přeuspořádají podle lightningcss a zastíněné duplicitní deklarace se odstraní.
  • Mezipaměti klíčované podle výstupu se jednou zneplatní. Mezipaměť souborů tw::generate() ve svém klíči neobsahuje verzi TailwindPHP, proto po upgradu spusťte tw::clearCache() (nebo adresář předaný jako cache). Mezipaměť stavu kompilátoru se zneplatní sama.
  • Nové: @variant v autorském CSS, mixiny CSS v @apply, @media reference a @import "…" reference, plný engine --value()/--modifier() pro funkční @utility, přísnější ověřování názvů @utility a volba polyfills v tw::compile().

1.6.1

  • Nové: utilita container (width: 100% plus jeden max-width pro každý breakpoint).
  • Složené proměnné --tw-* (translate, scale, rotate, skew, filtry a další) se nyní registrují v @property, takže styly získají pravidla @property a transformace jako translate-x-7 se projeví v prohlížeči.

1.6.0

  • Nové: trvalá mezipaměť stavu kompilátoru (stateCacheFile v tw::compile() a TailwindCompiler, StateCache\compileCssCached()) a oddělené funkce parseCssState()/finalizeCssState()/compileParsed(). Stávající volání se chovají přesně jako dříve.

1.5.0

  • Podtřídy TailwindCompiler, které přepisují generate() nebo css(), musí přidat volitelný parametr bool $minify = false; PHP odmítá přepisy, které vynechají volitelný parametr rodičovské třídy.
  • Minifikovaný výstup vytváří serializér, takže minifikované bajty se mírně liší od 1.4.x (mezipaměti klíčované podle minifikovaného výstupu se jednou zneplatní).
  • Nové: generateExact() a cssExact() pro CSS jednotlivých stránek z jediné dlouho žijící instance kompilátoru.