# Совместимость и обновление

На этой странице собрана информация, которая понадобится перед обновлением или при точном сравнении результатов: требования к среде выполнения, версии 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**. Репозиторий оригинального проекта закреплен в виде подмодуля git в `reference/tailwindcss`. Наборы тестов извлекаются из этой закрепленной копии, а тесты 4,427 запускаются при каждом отправлении изменений (см. раздел [Производительность и тестирование](https://tailwindphp.inline0.dev/ru/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/ru/docs/api#twextractcandidatesfromstrings) либо `@source inline("…")`. Формы путей в `@source` игнорируются API и учитываются CLI лишь частично (см. ниже).

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

| Область | Текущее поведение | Проблема |
|---|---|---|
| CLI `@source` | Пути и glob-шаблоны не применяются; вместо этого сканируется каталог входного файла, а `@source not` ничего не исключает. См. [Что сканирует CLI](https://tailwindphp.inline0.dev/ru/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/ru/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 для каждой страницы с помощью одного долго живущего компилятора.