# Zgodność i aktualizacja

Na tej stronie zebrano informacje potrzebne przed aktualizacją lub poleganiem na dokładnym wyniku: wymagania środowiska uruchomieniowego, wydanie TailwindCSS, za którym podąża port, znane różnice TailwindPHP względem TailwindCSS oraz uwagi dotyczące poszczególnych wydań. Pełna historia znajduje się w [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## Wymagania

- **PHP 8.2 lub nowszy.** Zestaw testów działa na PHP 8.2, 8.3 i 8.4.
- **Rozszerzenia `ctype` i `mbstring`.** Kompilator wywołuje `ctype_*` i `mb_chr()`. Są dołączane do większości buildów PHP i oficjalnych obrazów Docker, ale `composer.json` jeszcze ich nie deklaruje ([#11](https://github.com/inline0/tailwindphp/issues/11)), więc build bez nich zainstaluje pakiet, który nie zadziała w środowisku uruchomieniowym.
- **Opcjonalnie: `pcntl`** pozwala trybowi `--watch` CLI poprawnie kończyć działanie przy `SIGINT`/`SIGTERM`. Bez niego tryb watch nadal działa.

Nie używa Node.js, FFI ani binariów natywnych.

## Które wydanie TailwindCSS jest śledzone

Wydanie 1.7.0 śledzi **TailwindCSS v4.3.3**. Repozytorium nadrzędne jest przypięte jako podmoduł git w `reference/tailwindcss`, zestawy testów są wyodrębniane z przypiętej kopii, a testy 4,427 są uruchamiane przy każdym pushu (zobacz [Wydajność i testowanie](https://tailwindphp.inline0.dev/pl/docs/advanced/performance)). Przeniesione wtyczki są zgodne z `@tailwindcss/typography` i `@tailwindcss/forms`, a narzędzia klasowe z clsx, tailwind-merge i CVA; wszystkie są przypięte w ten sam sposób.

## Znane różnice względem TailwindCSS

### Szczegóły serializacji

Wygenerowany CSS przechodzi referencyjne zestawy testów. Niektóre szczegóły serializacji różnią się od wyniku TailwindCSS CLI, ale żadna z tych różnic nie zmienia kaskady:

- Prefiksy dostawców: gdy wersja referencyjna generuje zarówno zapisaną przez autora linię `-webkit-*`, jak i wygenerowaną, TailwindPHP emituje jedną linię.
- Pseudoelementy przekształcone do starszej składni (`::file-selector-button`, `::-webkit-datetime-edit-*`) pozostają na swoich listach selektorów zapisanych przez autora, zamiast być rozdzielane na osobną regułę dla każdego pseudoelementu.
- Zapisane przez autora ciągi w apostrofach pozostają w apostrofach (`'Segoe UI'`), zamiast być normalizowane do cudzysłowów.
- Współwystępujące właściwości pełne nie są łączone we właściwość skróconą (własny wynik Tailwind nigdy tego nie wymaga).
- `.p-0` zachowuje `padding: 0px` tam, gdzie wersja referencyjna CLI emituje `padding: 0`, ponieważ wyodrębniony zbiór testów wymaga postaci `0px`. Minifikator skraca ją do `0`.

### Poza zakresem

TailwindPHP to kompilator CSS. Nie obejmuje narzędzi edytorskich z ekosystemu Tailwind (IntelliSense, autouzupełniania, sortowania klas) ani map źródeł, dlatego CLI nie ma opcji `--map`.

### Skanowanie zawartości

`tw::generate()` i `TailwindCompiler::generate()` odczytują nazwy klas wyłącznie z atrybutów `class` i `className`. W przypadku nazw klas zapisanych w ciągach PHP lub JavaScript użyj [`tw::extractCandidatesFromStrings()`](https://tailwindphp.inline0.dev/pl/docs/api#twextractcandidatesfromstrings) albo `@source inline("…")`. Ścieżki w formacie `@source` są ignorowane przez API i tylko częściowo uwzględniane przez CLI (szczegóły poniżej).

### Znane problemy w bieżącym wydaniu

| Obszar | Obecne działanie | Problem |
|---|---|---|
| CLI `@source` | Ścieżki i wzorce glob nie są stosowane; zamiast tego skanowany jest katalog pliku wejściowego, a `@source not` niczego nie wyklucza. Zobacz [Co skanuje CLI](https://tailwindphp.inline0.dev/pl/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Minifikuje, podobnie jak `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Długie opcje CLI | `--input file.css` (oddzielone spacją) jest ignorowane; użyj `--input=file.css` lub `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Warianty wtyczek | Warianty `addVariant()`/`matchVariant()` i modyfikatory elementów typografii (`prose-headings:` …) są kompilowane bez selektora | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Mixiny `@apply` | `@apply --my-mixin;` jest usuwane zamiast przekazywane dalej | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Importy referencyjne | Wynik jest pusty, gdy import referencyjny poprzedza import narzędzi; `@import "tailwindcss" reference` nie ma wpływu | [#14](https://github.com/inline0/tailwindphp/issues/14) |

## Uwagi dotyczące aktualizacji

### 1.7.0

- **Wynik zmienia się bajtowo** względem 1.6.x, zachowując równoważność funkcjonalną z implementacją referencyjną TailwindCSS v4.3.3. Widoczne zmiany obejmują:
  - Mnożniki odstępów: `p-1` emituje `padding: var(--spacing)` zamiast `calc()`, a mnożnik `0` emituje zwykłą długość równą zero.
  - Ułamki są zamieniane na wartości procentowe: `w-1/2` emituje `width: 50%`.
  - Kolory: jasność `oklch()`/`oklab()` jest serializowana jako wartość procentowa (`oklch(62.3% .214 259.815)`), a `white` i `black` są skracane do `#fff` i `#000`.
  - Pseudoelementy CSS2 są serializowane z pojedynczym dwukropkiem (`:before`, `:after`, `:first-letter`, `:first-line`).
  - Zagnieżdżone reguły `@media`/`@supports`/`@container` są spłaszczane na miejscu, w kolejności źródłowej, zamiast być przenoszone na koniec; deklaracje są porządkowane tak, jak robi to lightningcss, a przesłonięte duplikaty deklaracji są usuwane.
- **Pamięci podręczne oparte na wyniku zostaną jednorazowo unieważnione.** Klucz pamięci podręcznej plików `tw::generate()` nie uwzględnia wersji TailwindPHP, więc po aktualizacji uruchom `tw::clearCache()` (lub katalog przekazany jako `cache`). Pamięć podręczna stanu kompilatora [cache stanu kompilatora](https://tailwindphp.inline0.dev/pl/docs/advanced/caching#compiler-state-cache) sama się unieważnia.
- **Nowości:** `@variant` w CSS autora, CSS mixiny w `@apply`, `@media reference` i `@import "…" reference`, pełny silnik `--value()`/`--modifier()` dla funkcjonalnego `@utility`, ściślejsza walidacja nazw `@utility` oraz opcja `polyfills` dla `tw::compile()`.

### 1.6.1

- **Nowość:** narzędzie `container` (`width: 100%` plus jeden `max-width` na każdy punkt przerwania).
- Złożone zmienne `--tw-*` (przesunięcie, skalowanie, obracanie, pochylenie, filtry i inne) są teraz zarejestrowane w `@property`, dzięki czemu arkusze stylów zyskują reguły `@property`, a transformacje takie jak `translate-x-7` działają w przeglądarce.

### 1.6.0

- **Nowość:** trwała pamięć podręczna stanu kompilatora (`stateCacheFile` w `tw::compile()` i `TailwindCompiler`, `StateCache\compileCssCached()`) oraz rozdzielone funkcje `parseCssState()`/`finalizeCssState()`/`compileParsed()`. Dotychczasowe wywołania działają dokładnie jak wcześniej.

### 1.5.0

- Podklasy `TailwindCompiler`, które nadpisują `generate()` lub `css()`, muszą dodać opcjonalny parametr `bool $minify = false`; PHP odrzuca nadpisania pomijające opcjonalny parametr klasy bazowej.
- Zminifikowany wynik pochodzi z serializatora, dlatego bajty wyniku po minifikacji nieco różnią się od 1.4.x (pamięci podręczne oparte na zminifikowanym wyniku zostaną jednorazowo unieważnione).
- **Nowość:** `generateExact()` i `cssExact()` do obsługi CSS dla poszczególnych stron z poziomu jednego długotrwałego kompilatora.