# Сумісність і оновлення

На цій сторінці зібрано все, що потрібно знати перед оновленням або використанням точного результату: вимоги до середовища виконання, за яким випуском TailwindCSS іде порт, у чому TailwindPHP свідомо відрізняється від TailwindCSS, а також примітки до кожного випуску. Повну історію наведено в [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## Вимоги

- **PHP 8.2 або новіша версія.** Набір тестів працює на PHP 8.2, 8.3 і 8.4.
- **Розширення `ctype` і `mbstring`.** Компілятор викликає `ctype_*` і `mb_chr()`. Обидва постачаються з більшістю збірок PHP та офіційними образами Docker, але `composer.json` поки їх не оголошує ([#11](https://github.com/inline0/tailwindphp/issues/11)), тому збірка без них встановлює пакет, але завершується помилкою під час виконання.
- **Необов’язково: `pcntl`** дає змогу режиму `--watch` CLI коректно зупинятися на `SIGINT`/`SIGTERM`. Без нього режим стеження також працює.

Не використовуються Node.js, FFI чи нативні двійкові файли.

## За яким випуском TailwindCSS іде порт

Випуск 1.7.0 відповідає **TailwindCSS v4.3.3**. Репозиторій upstream зафіксовано як підмодуль git у `reference/tailwindcss`, його набори тестів видобуваються з цього зафіксованого клону, а тести 4,427 запускаються під час кожного push (див. [Тестування продуктивності](https://tailwindphp.inline0.dev/uk/docs/advanced/performance)). Перенесені плагіни відповідають `@tailwindcss/typography` та `@tailwindcss/forms`, а утиліти класів — clsx, tailwind-merge і CVA; кожну залежність зафіксовано так само.

## Відомі відмінності від TailwindCSS

### Деталі серіалізації

Згенерований CSS відповідає еталонним наборам тестів. Деякі деталі серіалізації відрізняються від результату TailwindCSS CLI, але не впливають на каскад:

- Префікси виробників: якщо еталон виводить і авторський рядок `-webkit-*`, і згенерований, TailwindPHP виводить один рядок.
- Псевдоелементи, перетворені для старіших версій (`::file-selector-button`, `::-webkit-datetime-edit-*`), залишаються в авторських списках селекторів, а не розбиваються на окремі правила для кожного псевдоелемента.
- Авторські рядки в одинарних лапках залишаються в них (`'Segoe UI'`), а не нормалізуються до подвійних лапок.
- Властивості longhand, що трапляються разом, не об'єднуються у скорочений запис (у власному результаті Tailwind це ніколи не потрібно).
- `.p-0` зберігає `padding: 0px`, тоді як еталонний CLI виводить `padding: 0`, оскільки видобутий корпус тестів фіксує форму `0px`. Мініфікатор скорочує її до `0`.

### Що не включено

TailwindPHP — компілятор CSS. У ньому немає інструментів редактора з екосистеми Tailwind (IntelliSense, автодоповнення, сортування класів) і карт джерела, тому в CLI немає параметра `--map`.

### Сканування вмісту

`tw::generate()` і `TailwindCompiler::generate()` зчитують назви класів лише з атрибутів `class` і `className`. Для назв класів у рядках PHP або JavaScript використовуйте [`tw::extractCandidatesFromStrings()`](https://tailwindphp.inline0.dev/uk/docs/api#twextractcandidatesfromstrings) або `@source inline("…")`. Форми шляхів `@source` ігноруються в API і лише частково враховуються в CLI (див. нижче).

### Відомі проблеми поточного випуску

| Сфера | Поточна поведінка | Проблема |
|---|---|---|
| CLI `@source` | Шляхи та шаблони glob не застосовуються; натомість сканується каталог вхідного файла, а `@source not` нічого не виключає. Див. [Що сканує CLI](https://tailwindphp.inline0.dev/uk/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Виконує мініфікацію, як `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Довгі параметри CLI | `--input file.css` (через пробіл) ігнорується; використовуйте `--input=file.css` або `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Варіанти плагінів | Варіанти `addVariant()`/`matchVariant()` та модифікатори типографічних елементів (`prose-headings:` …) компілюються без свого селектора | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Міксини `@apply` | `@apply --my-mixin;` відкидається, а не передається далі | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Імпорти reference | Якщо імпорт reference стоїть перед імпортом утиліт, результат порожній; `@import "tailwindcss" reference` не діє | [#14](https://github.com/inline0/tailwindphp/issues/14) |

## Примітки до оновлення

### 1.7.0

- **Результат змінюється на рівні байтів** порівняно з 1.6.x, хоча функціонально він еквівалентний еталону TailwindCSS v4.3.3. Серед помітних змін:
  - Множники інтервалів: `p-1` виводить `padding: var(--spacing)` замість `calc()`, а множник `0` дає звичайну нульову довжину.
  - Дроби перетворюються на відсотки: `w-1/2` виводить `width: 50%`.
  - Кольори: яскравість `oklch()`/`oklab()` серіалізується як відсоток (`oklch(62.3% .214 259.815)`), `white` і `black` скорочуються до `#fff` і `#000`.
  - Псевдоелементи CSS2 серіалізуються з однією двокрапкою (`:before`, `:after`, `:first-letter`, `:first-line`).
  - Вкладені правила `@media`/`@supports`/`@container` розгортаються на місці в порядку джерела, а не переносяться в кінець; оголошення впорядковуються як у lightningcss; затінені дубльовані оголошення видаляються.
- **Кеші, ключем яких є результат, буде скинуто один раз.** Ключ файлового кешу `tw::generate()` не містить версії TailwindPHP, тому після оновлення запустіть `tw::clearCache()` (або каталог, переданий як `cache`). Кеш [стану компілятора](https://tailwindphp.inline0.dev/uk/docs/advanced/caching#compiler-state-cache) сам себе скидає.
- **Нове:** `@variant` в авторському CSS, міксини CSS в `@apply`, `@media reference` та `@import "…" reference`, повний рушій `--value()`/`--modifier()` для функціонального `@utility`, суворіша перевірка назв `@utility` і параметр `polyfills` у `tw::compile()`.

### 1.6.1

- **Нове:** утиліта `container` (`width: 100%` плюс один `max-width` для кожної контрольної точки).
- Змінні `--tw-*` тепер реєструються в `@property` (переміщення, масштабування, обертання, нахил, фільтри тощо), тож таблиці стилів отримують правила `@property`, а перетворення на кшталт `translate-x-7` починають діяти в браузері.

### 1.6.0

- **Нове:** постійний кеш стану компілятора (`stateCacheFile` для `tw::compile()` і `TailwindCompiler`, `StateCache\compileCssCached()`), а також окремі функції `parseCssState()`/`finalizeCssState()`/`compileParsed()`. Наявні виклики працюють так само, як і раніше.

### 1.5.0

- Підкласи `TailwindCompiler`, що перевизначають `generate()` або `css()`, мають додати необов'язковий параметр `bool $minify = false`; PHP відхиляє перевизначення, у яких пропущено необов'язковий параметр батьківського класу.
- Мініфікований результат створює серіалізатор, тому байти відрізняються від 1.4.x (кеші мініфікованого результату буде скинуто один раз).
- **Нове:** `generateExact()` і `cssExact()` для CSS окремих сторінок з одного компілятора, який працює тривалий час.