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

Переглянути як 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. Репозиторій upstream зафіксовано як підмодуль git у reference/tailwindcss, його набори тестів видобуваються з цього зафіксованого клону, а тести 4,427 запускаються під час кожного push (див. Тестування продуктивності). Перенесені плагіни відповідають @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() або @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
Імпорти reference	Якщо імпорт reference стоїть перед імпортом утиліт, результат порожній; `@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 окремих сторінок з одного компілятора, який працює тривалий час.