# Kompatibilita a upgrade

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](https://github.com/inline0/tailwindphp/blob/main/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](https://github.com/inline0/tailwindphp/issues/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í](https://tailwindphp.inline0.dev/cs/docs/advanced/performance)). 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()`](https://tailwindphp.inline0.dev/cs/docs/api#twextractcandidatesfromstrings) 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](https://tailwindphp.inline0.dev/cs/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Minifikuje stejně jako `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Dlouhé volby CLI | `--input file.css` (oddělené mezerou) se ignoruje; použijte `--input=file.css` nebo `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Varianty pluginů | Varianty `addVariant()`/`matchVariant()` a modifikátory typografických elementů (`prose-headings:` …) se kompilují bez selektoru | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Mixiny `@apply` | `@apply --my-mixin;` se zahodí místo předání dál | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Referenční importy | Výstup je prázdný, pokud import referencí předchází importu utilit; `@import "tailwindcss" reference` nemá žádný účinek | [#14](https://github.com/inline0/tailwindphp/issues/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](https://tailwindphp.inline0.dev/cs/docs/advanced/caching#compiler-state-cache) 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.