Кэширование и минификация

На заключительном этапе конвейера возникают три задачи, связанные с использованием в production: избежать повторной компиляции одинаковых входных данных, не создавать компилятор при каждом запросе и уменьшить размер сгенерированного 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.