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

Просмотреть как Markdown Редактировать на GitHub Документация по 3843abd

На этой странице собрана информация, которая понадобится перед обновлением или при точном сравнении результатов: требования к среде выполнения, версии TailwindCSS, с которыми совместим порт, известные отличия реализации TailwindPHP от TailwindCSS и примечания к каждому выпуску. Полная история изменений приведена в CHANGELOG.md.

Требования

PHP версии 8.2 или новее. Набор тестов запускается на PHP версий 8.2, 8.3 и 8.4.
Расширения ctype и mbstring. Компилятор вызывает ctype_* и mb_chr(). Они входят в большинство сборок PHP и официальные образы Docker, но composer.json пока не объявляет их зависимостями (#11), поэтому сборка без них установит пакет, но тот не запустится.
Необязательно: pcntl. Позволяет режиму --watch у CLI корректно останавливаться при получении SIGINT/SIGTERM. Без него режим наблюдения по-прежнему работает.

Здесь не используются Node.js, FFI или нативные двоичные файлы.

Версия TailwindCSS, с которой синхронизируется порт

Порт версии 1.7.0 синхронизирован с TailwindCSS v4.3.3. Репозиторий оригинального проекта закреплен в виде подмодуля git в reference/tailwindcss. Наборы тестов извлекаются из этой закрепленной копии, а тесты 4,427 запускаются при каждом отправлении изменений (см. раздел Производительность и тестирование). Перенесенные плагины соответствуют @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() либо @source inline("…"). Формы путей в @source игнорируются API и учитываются CLI лишь частично (см. ниже).

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

Область	Текущее поведение	Проблема
CLI `@source`	Пути и glob-шаблоны не применяются; вместо этого сканируется каталог входного файла, а `@source not` ничего не исключает. См. Что сканирует CLI	#8
CLI `--optimize`	Минифицирует, как `--minify`	#9
Длинные параметры CLI	`--input file.css` (разделенные пробелами) игнорируются; используйте `--input=file.css` или `-i file.css`	#13
Варианты плагинов	Варианты `addVariant()`/`matchVariant()` и модификаторы типографических элементов (`prose-headings:` …) компилируются без селектора	#10
Миксины `@apply`	`@apply --my-mixin;` удаляется вместо передачи дальше	#12
Импорты эталонной реализации	Если перед импортом утилит указан эталонный импорт, результат пуст; `@import "tailwindcss" reference` не влияет	#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). кэш состояния компилятора обновляется автоматически.
Новое: @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 для каждой страницы с помощью одного долго живущего компилятора.