Kompatibilita a aktualizácia

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 3843abd

Táto stránka zhŕňa, čo treba vedieť pred aktualizáciou alebo pri požiadavke na presne rovnaký výstup: požiadavky na behové prostredie, ktoré vydanie TailwindCSS nasleduje, v čom sa TailwindPHP zámerne líši od TailwindCSS a poznámky ku každému vydaniu. Úplná história je v CHANGELOG.md.

Požiadavky

PHP 8.2 alebo novší. Testovacia sada sa spúšťa na verziách PHP 8.2, 8.3 a 8.4.
Rozšírenia ctype a mbstring. Kompilátor volá ctype_* a mb_chr(). Sú súčasťou väčšiny zostavení PHP aj oficiálnych obrazov Docker, ale composer.json ich zatiaľ neuvádza ako závislosti (#11), takže zostavenie bez nich balík nainštaluje, no pri behu zlyhá.
Voliteľné: pcntl umožňuje režimu CLI --watch korektne sa zastaviť pri SIGINT/SIGTERM. Bez neho režim sledovania stále funguje.

Nepoužíva sa Node.js, FFI ani natívne binárne súbory.

Ktoré vydanie TailwindCSS sa sleduje

Vydanie 1.7.0 sleduje TailwindCSS v4.3.3. Nadriadené úložisko je pripnuté ako podmodul git v reference/tailwindcss, jeho testovacie sady sa získavajú z pripnutej kópie a testy 4,427 sa spúšťajú pri každom pushnutí (pozrite si Testovanie výkonu). Prenesené doplnky sa riadia podľa @tailwindcss/typography a @tailwindcss/forms a pomocné triedy podľa clsx, tailwind-merge a CVA; všetky sú pripnuté rovnakým spôsobom.

Známe rozdiely oproti TailwindCSS

Podrobnosti serializácie

Vygenerovaný CSS zodpovedá referenčným testovacím sadám. Niekoľko podrobností serializácie sa líši od výstupu TailwindCSS CLI, ale žiadna z týchto odlišností nemení kaskádu:

Predpony dodávateľov: ak referencia vypíše autorský riadok -webkit-* aj vygenerovaný riadok, TailwindPHP vypíše jeden riadok.
Pseudoprvky prevedené na staršiu syntax (::file-selector-button, ::-webkit-datetime-edit-*) zostávajú vo svojich pôvodných zoznamoch selektorov namiesto rozdelenia na jedno pravidlo pre každý pseudoprvok.
Pôvodné reťazce v jednoduchých úvodzovkách zostávajú v jednoduchých úvodzovkách ('Segoe UI'), namiesto zmeny na dvojité úvodzovky.
Súvisiace dlhé zápisy sa nezlučujú do skráteného zápisu (vlastný výstup Tailwind to nikdy nepotrebuje).
.p-0 zachováva padding: 0px tam, kde referencia CLI vypisuje padding: 0, pretože získaný testovací korpus používa formu 0px. Minifikátor ju skracuje na 0.

Čo nie je zahrnuté

TailwindPHP je kompilátor CSS. Neobsahuje nástroje editora z ekosystému Tailwind (IntelliSense, automatické dopĺňanie, triedenie tried) ani zdrojové mapy, preto CLI nemá možnosť --map.

Skenovanie obsahu

tw::generate() a TailwindCompiler::generate() čítajú názvy tried iba z atribútov class a className. Pri názvoch tried uložených v reťazcoch PHP alebo JavaScript použite tw::extractCandidatesFromStrings() alebo @source inline("…"). Cesty v @source prekladač API ignoruje a kompilátor CLI zohľadňuje len čiastočne (pozrite nižšie).

Známe problémy v aktuálnom vydaní

Oblasť	Aktuálne správanie	Problém
CLI `@source`	Cesty a vzory glob sa nepoužívajú; skenuje sa namiesto nich adresár vstupného súboru a `@source not` nič nevylučuje. Pozrite si Čo skenuje CLI	#8
CLI `--optimize`	Minifikuje rovnako ako `--minify`	#9
Dlhé možnosti CLI	`--input file.css` (oddelené medzerami) sa ignoruje; použite `--input=file.css` alebo `-i file.css`	#13
Varianty doplnkov	Varianty `addVariant()`/`matchVariant()` a modifikátory typografických prvkov (`prose-headings:` …) sa skompilujú bez svojho selektora	#10
Mixiny `@apply`	`@apply --my-mixin;` sa zahodí namiesto toho, aby sa ponechal bez zmeny	#12
Referenčné importy	Výstup je prázdny, keď import referencie predchádza importu nástrojov; `@import "tailwindcss" reference` nemá žiadny účinok	#14

Poznámky k aktualizácii

1.7.0

Výstup sa bajtovo líši od 1.6.x, hoci je funkčne rovnocenný s referenčným TailwindCSS v4.3.3. Medzi viditeľné zmeny patria:
- Násobitele medzier: p-1 vypíše padding: var(--spacing) namiesto calc() a násobiteľ 0 vypíše ako obyčajnú nulovú dĺžku.
- Zlomky sa prevádzajú na percentá: w-1/2 vypíše width: 50%.
- Farby: svetlosť oklch()/oklab() sa serializuje ako percento (oklch(62.3% .214 259.815)), white a black sa skracujú na #fff a #000.
- Pseudoprvky CSS2 sa serializujú s jednou dvojbodkou (:before, :after, :first-letter, :first-line).
- Vnorené pravidlá @media/@supports/@container sa rozvinú na mieste a v poradí zdrojového kódu namiesto presunu na koniec; deklarácie sa zoradia tak, ako ich radí lightningcss, a prekryté duplicitné deklarácie sa odstránia.
Vyrovnávacie pamäte s kľúčom podľa výstupu sa raz zneplatnia. Kľúč súborovej vyrovnávacej pamäte tw::generate() nezahŕňa verziu TailwindPHP, preto po aktualizácii spustite tw::clearCache() (alebo adresár odovzdaný ako cache). Vyrovnávacia pamäť stavu kompilátora compiler state cache sa zneplatňuje sama.
Nové: @variant v autorskom CSS, mixiny CSS v @apply, @media reference a @import "…" reference, kompletné prostredie --value()/--modifier() pre funkčné @utility, prísnejšie overovanie názvov @utility a možnosť polyfills pre tw::compile().

1.6.1

Nové: nástroj container (width: 100% a jedno max-width na každý bod zlomu).
Zložené premenné --tw-* (posun, zmena mierky, otočenie, skosenie, filtre a ďalšie) sú teraz registrované v @property, takže štýly získajú tieto pravidlá @property a transformácie ako translate-x-7 sa prejavia v prehliadači.

1.6.0

Nové: trvalá vyrovnávacia pamäť stavu kompilátora (stateCacheFile v tw::compile() a TailwindCompiler, StateCache\compileCssCached()) a rozdelené funkcie parseCssState()/finalizeCssState()/compileParsed(). Existujúce volania sa správajú presne ako predtým.

1.5.0

Podtriedy TailwindCompiler, ktoré preťažujú generate() alebo css(), musia pridať voliteľný parameter bool $minify = false; PHP odmieta preťaženia, ktoré vynechajú voliteľný parameter rodičovskej triedy.
Minifikovaný výstup vytvára serializátor, takže minifikované bajty sa mierne líšia od 1.4.x (vyrovnávacie pamäte s kľúčom podľa minifikovaného výstupu sa raz zneplatnia).
Nové: generateExact() a cssExact() na vytváranie CSS pre jednotlivé stránky z jedného dlho žijúceho kompilátora.