Кешування та мініфікація

На етапі конвеєра виникають три завдання для виробничого середовища: уникнути повторної компіляції незмінних вхідних даних, не створювати компілятор для кожного запиту та зменшити згенерований CSS. Усі три розв’язують допоміжні засоби на стороні PHP навколо компілятора.

Кешування

Для генерації CSS весь конвеєр запускається під час кожного виклику. Якщо вміст не змінюється між запитами, файловий кеш записує результат на диск і під час наступних викликів віддає його звідти.

Передайте cache до tw::generate() — true для каталогу за замовчуванням або рядок зі шляхом до власного каталогу:

use TailwindPHP\tw;

// Cache to the default directory: sys_get_temp_dir() . '/tailwindphp'
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
]);

// Cache to a custom directory
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => '/path/to/cache',
]);

// With a time-to-live (seconds)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
    'cacheTtl' => 3600, // expire after 1 hour
]);

Якщо каталогу кешу немає, його буде створено автоматично.

Ключ кешу

Ключ обчислюється на основі вмісту, конфігурації CSS та прапорця minify й хешується для формування імені файлу tailwind_<hash>.css. Будь-яка зміна розмітки, вхідних даних CSS або стану мініфікації створює інший ключ і, відповідно, інший файл.

Конфігурація CSS у ключі охоплює вбудований css і вміст файлів, названих у importPaths. Два типи вхідних даних не враховуються: файли, підключені вкладеним @import у цих файлах, і версія TailwindPHP. Очистьте кеш після редагування вкладеного імпорту або оновлення пакета, інакше повертатиметься старий результат.

Час життя

cacheTtl — це час життя у секундах. У разі влучання в кеш час зміни файлу порівнюється з поточним часом; якщо файл старіший за cacheTtl, це вважається промахом кешу, і компіляція запускається знову. Якщо cacheTtl не задано, записи не застарівають — очищайте їх вручну.

Очищення кешу

tw::clearCache() (або функція clearCache()) видаляє файли tailwind_*.css з каталогу кешу й повертає кількість видалених файлів.

use TailwindPHP\tw;
use function TailwindPHP\clearCache;

$deleted = tw::clearCache();                  // default directory
$deleted = tw::clearCache('/path/to/cache');  // custom directory
clearCache('/path/to/cache');                 // function form

Кеш стану компілятора

Кеш результатів допомагає, лише коли вміст повторюється. Якщо під час кожного виклику вміст змінюється, найбільше часу забирає створення самого компілятора: розв’язання @import "tailwindcss", розбір упакованих ресурсів і накопичення теми. Цей етап залежить лише від вхідних даних CSS, тому його можна зберегти й повторно використати.

Передайте stateCacheFile до tw::compile() (або new TailwindCompiler($css, $options)):

use TailwindPHP\tw;

$compiler = tw::compile($themeCss, [
    'stateCacheFile' => __DIR__ . '/cache/tailwind-state.php',
]);

$css = $compiler->generateExact($html, true);

Під час першого створення стан записується за цим шляхом у звичайний файл PHP, яким OPcache може користуватися в кількох запитах; під час наступних створень він завантажується з файлу без повторного розбору. Результат побайтно ідентичний результату компілятора без кешу.

• Файл перевіряється за відбитком рушія (розміром і часом зміни вихідних файлів і ресурсів TailwindPHP), ключем на основі вхідних даних CSS, параметрів base і importSearchPaths, а також розміру й часу зміни кожного імпортованого вхідними даними файлу. У разі невідповідності файл перебудовується й перезаписується, тож оновлення TailwindPHP або редагування імпортованого файлу не потребує ручних дій.
• Ви відповідаєте за шлях: використовуйте окремий файл для кожних вхідних даних CSS у каталозі, доступному для запису вебсерверу. Запис виконується атомарно (тимчасовий файл і rename()).
• Для вхідних даних із власним importResolver кеш не використовується, оскільки поведінку розв’язувача неможливо відстежити за відбитком.
• Той самий кеш можна використовувати з низькорівневим масивом compile() API як TailwindPHP\StateCache\compileCssCached($css, $cacheFile, $options).

tw::generate() не приймає stateCacheFile; він створює новий компілятор під час кожного виклику. Якщо важлива вартість створення, використовуйте екземпляр компілятора.

Мінімізація

Мініфікація зменшує розмір результату для production. Прапорець minify виводить мініфікований CSS безпосередньо під час серіалізації, тож це найшвидший і найточніший спосіб; tw::minify() запускає мініфікатор на основі рядків (src/_tailwindphp/CssMinifier.php) для наявного рядка CSS:

use TailwindPHP\tw;

// Minify during generation (serializer path, preferred)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'minify' => true,
]);

// Or minify an existing string (string-based post-pass)
$css = tw::generate('<div class="flex p-4">Hello</div>');
$minified = tw::minify($css);

Обидва способи дають еквівалентну структуру, але байти не збігаються. Спосіб серіалізації зберігає селектори нащадків :not(), які рядковий етап згортає, тож для згенерованого результату надавайте перевагу прапорцю minify, а tw::minify() залиште для CSS, що надходить як рядок.

Що він робить

Обидва способи застосовують однаковий набір скорочень розміру:

За задумом він не об'єднує дубльовані селектори чи скорочені властивості — це ускладнює налагодження та може вплинути на каскад.

CLI: --minify проти --optimize

CLI надає доступ до шляху мініфікації серіалізатора через два прапорці:

# Optimize and minify (smallest output)
tailwindphp -i ./src/app.css -o ./dist/styles.css --minify   # or -m

# Meant to optimize without minifying
tailwindphp -i ./src/app.css -o ./dist/styles.css --optimize

У поточному випуску --optimize також виконує мініфікацію, тож обидві команди записують однакові байти (#9). Еквівалентні перетворення lightningcss виконуються під час кожної збірки, тому звичайний результат (без прапорця) вже оптимізований і зручний для читання.

Щоб дізнатися про решту публічного API — tw::generate(), tw::compile(), методи перевірки та формати вводу — див. довідник API.