Výkon a testování

Zobrazit jako Markdown Upravit na GitHub Dokumentace na 3843abd

TailwindPHP upřednostňuje především správnost. Pokud změna specifická pro PHP zrychlí běh bez změny výstupu, použije se a označí jako @port-deviation:performance. Shoda s TailwindCSS se nepředpokládá — průběžně se ověřuje pomocí vlastní testovací sady Tailwind.

Výkon

Port PHP upřednostňuje shodu s výstupem TailwindCSS před hrubou propustností a původní TypeScript zůstává v každém případě rychlejší — JIT v V8 kompiluje často používané části do nativního kódu, čehož PHP nedokáže dosáhnout. Pro CSS generované při každém požadavku nebo na každé stránce znovu použijte jeden kompilátor (viz generateExact()) a jeho stav při konstrukci uchovávejte pomocí stateCacheFile.

Několik často používaných částí obsahuje ručně laděné optimalizace, které zachovávají totožný výstup:

ast.php toCss() — shromažďuje části do pole a jednou je spojí pomocí implode, místo aby opakovaně zřetězovala řetězce; používá také předem vypočítané řetězce odsazení.
css-parser.php — porovnává znaky přímo, bez volání ord(), a sleduje délky vyrovnávací paměti, místo aby opakovaně počítal strlen().

Obě optimalizace jsou zdokumentované pomocí @port-deviation:performance a podmíněné úspěšným průchodem testovací sady — nemohou změnit generované CSS.

Srovnávací testy

Adresář benchmarks/ obsahuje nástroj pro srovnávací testy. Spusťte jej takto:

Shell

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

Ukázkové výsledky na PHP 8.4.5 / Node.js v22.17.0 (Apple M1):

Srovnávací test	PHP	TypeScript
`css-parser` na preflight.css	~816 ops/s	~15.45K ops/s (≈20× rychlejší)
`toCss`	~65.85K ops/s	~2.59M ops/s (≈39× rychlejší)

TypeScript je u těchto nízkoúrovňových operací podle očekávání rychlejší. Pro generování celých stránek CSS, což je skutečný případ použití, je výkon PHP dostačující (v ukázkovém běhu přibližně 14 ms na stránku). Při opakovaném použití stejného vstupu náklady zcela odstraní mezipaměť souborů.

Testování a shoda

Testy zajišťují, že port PHP vytváří stejný výstup jako TailwindCSS. Společně se používají dva přístupy.

1. Testy založené na extrakci. Skripty v test-coverage/ analyzují vlastní soubory .test.ts projektu TailwindCSS a extrahují z nich testovací případy do JSON. PHPUnit pak tyto případy předá do TailwindPHP a porovná výstup s očekávaným CSS. Protože očekávané hodnoty pocházejí přímo z upstreamu, každá odchylka v chování PHP se projeví jako chyba. Testy pokrývají složité části: utility, varianty, integraci, funkce CSS a testy ui.spec na úrovni prohlížeče.

2. Ručně portované jednotkové testy. Jednodušší testovací soubory TypeScript (AST, parsování CSS, escapování, parsování kandidátů, parsování hodnot a další) se portují přímo do PHP a ukládají vedle zdrojového kódu jako *.test.php; kopírují strukturu i ověřování původních testů.

Cyklus má podobu extrahovat → spustit → ověřit: znovu extrahovat z aktuální reference TailwindCSS, spustit testovací sadu a každou odchylku zachytit jako chybu. Port tak drží krok s upstreamem a aktualizaci TailwindCSS lze ověřit automaticky, nikoli kontrolovat ručně. Při odchylce CI selže.

Shell

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

K vydání 1.7.0 je k dispozici 4,427 úspěšných testů (reference TailwindCSS v4.3.3):

Sada	Testy	Zdroj
Extrahované TailwindCSS sady (nástroje 706, varianty 164, index 148, css-functions 64, `ui.spec` 68)	1,150	extrahováno z `.test.ts` / `.spec.ts`
Pokrytí API (nástroje, modifikátory, varianty, direktivy, pluginy, importy, `@source`, ukládání do mezipaměti, veřejné API)	2,252	`tests/`
Jednotkové testy vedle zdrojového kódu (parser, AST, kandidáti, motiv, nástroje, parser selektorů, transformace lightningcss, minifikátor)	767	porty `*.test.php` a testy specifické pro PHP
CLI (zpracování argumentů, výstup, sestavení)	84	`tests/Cli*Test.php`
Porty pluginů (typografie, formuláře)	45	`*.test.php` vedle pluginů
Doprovodné knihovny (clsx, tailwind-merge, CVA)	129	referenční sady

Kvalita kódu

Formátování a statická analýza probíhají pomocí skriptů Composer:

Shell

composer lint      # Pint --test  (check formatting)
composer format    # Pint         (fix formatting)
composer analyse   # PHPStan      (static analysis, level 4)
composer quality   # lint + analyse

PHPStan běží na úrovni 4 (phpstan.neon), s krátkým seznamem ignorovaných vzorů pro dynamické tvary polí používané architekturou založenou na funkcích. Analyzují se všechny zdrojové soubory; testovací soubory jsou vyloučeny.

Strukturu ověřovanou těmito testy a zaznamenané odchylky popisuje Architektura.