# Съвместимост и надграждане

Тази страница събира важната информация, преди да надградите или да разчитате на точен изход: изискванията към средата за изпълнение, изданието на 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`, тестовите му набори се извличат от този фиксиран checkout, а тестовете на 4,427 се изпълняват при всяко изпращане на промени (вижте [Производителност и тестване](https://tailwindphp.inline0.dev/bg/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'`), вместо да се нормализират до двойни.
- Съвместно срещащите се дълги свойства не се обединяват в съкратено свойство (собственият изход на 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/bg/docs/api#twextractcandidatesfromstrings) или `@source inline("…")`. Формите на пътя за `@source` се игнорират от API и се поддържат само частично от CLI (вижте по-долу).

### Известни проблеми в текущото издание

| Област | Текущо поведение | Проблем |
|---|---|---|
| CLI `@source` | Пътищата и шаблоните не се прилагат; вместо това се сканира директорията на входния файл, а `@source not` не изключва нищо. Вижте [Какво сканира CLI](https://tailwindphp.inline0.dev/bg/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) |
| Референтни импорти | Изходът е празен, когато референтен импорт предхожда импорта на помощните класове; `@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/bg/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 на страница от един дълготрайно работещ компилатор.