API

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

Весь статический интерфейс собран в одном классе: TailwindPHP\tw (псевдоним внутреннего класса Tailwind). Все методы можно вызывать статически, а методы просмотра (properties, computedProperties, value, computedValue) принимают все описанные в конце страницы форматы ввода.

При повторной работе с одной конфигурацией CSS вызовите tw::compile() один раз и повторно используйте полученный экземпляр TailwindCompiler.

PHP

use TailwindPHP\tw;

$css = tw::generate('<div class="flex items-center p-4 bg-blue-500">');

tw::generate()

PHP

public static function generate(string|array $input, string $css = '@import "tailwindcss";'): string

Разбирает содержимое, извлекает кандидаты классов и возвращает сгенерированный CSS. По умолчанию используется $css — @import "tailwindcss";, включающий тему, preflight и утилиты. Возвращает string.

PHP

use TailwindPHP\tw;

// String input
$css = tw::generate('<div class="flex p-4">');

// String with custom CSS
$css = tw::generate('<div class="flex bg-brand">', '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

// Array input with options
$css = tw::generate([
    'content' => '<div class="flex p-4">',
    'css' => '@import "tailwindcss";',
    'minify' => true,
]);

Форма с массивом принимает следующие ключи:

Ключ	Тип	Назначение
`content`	`string`	Содержимое для поиска кандидатов классов (обязательный параметр)
`css`	`string`	Входной CSS с директивами Tailwind (по умолчанию `@import "tailwindcss";`)
`minify`	`bool`	Минифицировать результат (по умолчанию `false`)
`importPaths`	`string \| array \| callable \| null`	Загружать CSS из файловой системы с полным разрешением `@import` — см. Импорт CSS
`cache`	`bool \| string`	Включить файловое кэширование — см. Кэширование
`cacheTtl`	`int`	Срок хранения кэша в секундах

tw::compile()

PHP

public static function compile(string $css = '@import "tailwindcss";', array $options = []): TailwindCompiler

Создаёт повторно используемый экземпляр TailwindCompiler, привязанный к заданной CSS. Разбор и создание дизайн-системы выполняются один раз, поэтому этот вариант эффективен, когда нужно генерировать CSS для множества разных строк содержимого. Используйте generate(), чтобы накапливать одну таблицу стилей между вызовами, или generateExact() для независимого результата каждой страницы. Возвращает TailwindCompiler.

PHP

use TailwindPHP\tw;

// Default Tailwind
$compiler = tw::compile();

// Custom CSS
$compiler = tw::compile('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

$css = $compiler->generate('<div class="flex p-4 bg-brand">');

Массив $options принимает:

Параметр	Тип	Назначение
`stateCacheFile`	`string`	Путь к файлу PHP, сохраняющему состояние создания компилятора между запросами и процессами — см. Кэш состояния компилятора
`polyfills`	`int`	Какие резервные значения добавлять; задаётся битовой маской `TailwindPHP\POLYFILL_AT_PROPERTY` (значения по умолчанию `@layer properties` для переменных `@property`) и `TailwindPHP\POLYFILL_COLOR_MIX` (статические резервные цвета перед `color-mix()`). По умолчанию `POLYFILL_ALL`; `POLYFILL_NONE` отключает оба варианта
`importSearchPaths`	`array<string>`	Директории для поиска при разрешении `@import` из файловой системы

PHP

use TailwindPHP\tw;
use const TailwindPHP\POLYFILL_NONE;

// Cache construction state on disk, reused by later requests
$compiler = tw::compile('@import "tailwindcss";', [
    'stateCacheFile' => __DIR__ . '/cache/tailwind-state.php',
]);

// Plain output without fallbacks, e.g. for CSS modules
$compiler = tw::compile('@import "tailwindcss/utilities.css";', [
    'polyfills' => POLYFILL_NONE,
]);
$compiler->generate('<div class="bg-red-500/50">');
// .bg-red-500\/50 { background-color: color-mix(in oklab, var(--color-red-500) 50%, transparent); }
// (with the default, a `#fb2c3680` fallback comes first and color-mix() moves into @supports)

Полный список методов экземпляра см. в разделе Методы экземпляра TailwindCompiler.

tw::properties()

PHP

public static function properties(string|array $input, string $css = '@import "tailwindcss";'): array

Возвращает необработанные свойства CSS для класса; переменные CSS остаются неразрешёнными. Возвращает array<string, string> (имя свойства → значение).

PHP

use TailwindPHP\tw;

tw::properties('p-4');
// ['padding' => 'calc(var(--spacing) * 4)']

tw::properties(['flex', 'items-center', 'p-4']);
// ['display' => 'flex', 'align-items' => 'center', 'padding' => 'calc(var(--spacing) * 4)']

tw::computedProperties()

PHP

public static function computedProperties(string|array $input, string $css = '@import "tailwindcss";'): array

Как properties(), но все переменные CSS заменяются конкретными значениями. Возвращает array<string, string>.

PHP

use TailwindPHP\tw;

tw::computedProperties('p-4');
// ['padding' => '1rem']

tw::computedProperties('text-blue-500');
// ['color' => 'oklch(62.3% .214 259.815)']

tw::computedProperties(['flex', 'items-center', 'gap-4']);
// ['display' => 'flex', 'align-items' => 'center', 'gap' => '1rem']

tw::value()

PHP

public static function value(string|array $input, string $css = '@import "tailwindcss";'): ?string

Возвращает необработанное значение одного класса утилиты. Возвращает ?string — null, если утилита не найдена.

PHP

use TailwindPHP\tw;

tw::value('p-4');           // 'calc(var(--spacing) * 4)'
tw::value('text-blue-500'); // 'var(--color-blue-500)'

tw::computedValue()

PHP

public static function computedValue(string|array $input, string $css = '@import "tailwindcss";'): ?string

Возвращает разрешённое значение одного класса утилиты. Возвращает ?string — null, если утилита не найдена.

PHP

use TailwindPHP\tw;

tw::computedValue('p-4');           // '1rem'
tw::computedValue('text-blue-500'); // 'oklch(62.3% .214 259.815)'
tw::computedValue('gap-4');         // '1rem'

tw::extractCandidates()

PHP

public static function extractCandidates(string $html): array

Извлекает имена классов Tailwind из содержимого (читает атрибуты class и className). Возвращает array<string>.

PHP

use TailwindPHP\tw;

tw::extractCandidates('<div class="flex p-4" className="bg-blue-500">');
// ['flex', 'p-4', 'bg-blue-500']

tw::extractCandidatesFromStrings()

PHP

public static function extractCandidatesFromStrings(string $source): array

Извлекает кандидаты на имена классов из каждой строки в одинарных или двойных кавычках в исходном коде. Подходит для шаблонов, где списки классов формируются в переменных, а не в атрибутах class. Каждая строка разбивается по пробельным символам, и сохраняются все токены, похожие на имена классов. Возвращает array<string>.

PHP

use TailwindPHP\tw;

$classes = tw::extractCandidatesFromStrings('<?php $wrap = \'p-4 sm:flex\'; $title = "hello world"; ?>');
// ['p-4', 'sm:flex', 'hello', 'world']

$css = tw::compile()->css($classes);

Проверку проходят и обычные слова (выше: hello, world); они ни во что не компилируются, если только не совпадают с именами утилит. Передайте результат в css(), поскольку generate() читает только атрибуты class.

tw::cssMap()

PHP

public static function cssMap(string $css = '@import "tailwindcss";'): array

Создаёт обратное сопоставление объявлений CSS классам утилит; его удобно использовать для преобразования существующих CSS в классы Tailwind. Ключи — строки "property: value" с подставленными значениями переменных (для утилит с несколькими свойствами также создаётся ключ "prop: value; prop: value"), значения — имена классов. Возвращает array<string, string>.

PHP

use TailwindPHP\tw;

$map = tw::cssMap();
$map['display: flex'];       // 'flex'
$map['padding: 1rem'];       // 'p-4'
$map['text-align: center'];  // 'text-center'
$map['color: #fff'];         // 'text-white'

Сопоставление охватывает фиксированный список распространённых утилит (display, position, flexbox, типографика, шаги отступов и размеров, границы, чёрный, белый и прозрачный цвета и подобные), но не все утилиты и цвета темы. Параметр $css изменяет разрешённые значения этих утилит, однако пользовательские токены темы, например --color-brand, не добавляют новых записей.

tw::minify()

PHP

public static function minify(string $css): string

Минифицирует произвольную строку CSS: удаляет комментарии, объединяет пробелы, сокращает шестнадцатеричные цвета (#ffffff → #fff), убирает единицы измерения у нулевых значений (0px → 0) и выполняет другие преобразования. Возвращает string.

Для CSS, который самостоятельно генерирует TailwindPHP, предпочтительнее параметр minify (tw::generate(['minify' => true])) или параметр $minify методов компилятора. Этот способ выполняет минификацию при сериализации, что быстрее и сохраняет селекторы :not() дочерних элементов, которые строковая обработка сводит воедино.

PHP

use TailwindPHP\tw;

$css = tw::generate('<div class="flex p-4">');
$minified = tw::minify($css);

Полный список оптимизаций см. в разделе Кэширование и минификация.

tw::clearCache()

PHP

public static function clearCache(string|bool|null $cache = true): int

Удаляет закэшированные файлы CSS. Передайте true (или опустите параметр), чтобы использовать каталог кэша по умолчанию, либо строку с путём к пользовательскому каталогу. Возвращает int — количество удалённых файлов.

PHP

use TailwindPHP\tw;

tw::clearCache();                  // default directory
tw::clearCache('/path/to/cache');  // custom directory

Также доступна отдельная функция TailwindPHP\clearCache().

tw::colors()

PHP

public static function colors(string $css = '@import "tailwindcss";'): array

Возвращает все значения цветов из темы. Возвращает array<string, string> (имя цвета → вычисленное значение).

PHP

use TailwindPHP\tw;

tw::colors();
// ['red-500' => 'oklch(63.7% .237 25.331)', 'blue-500' => 'oklch(62.3% .214 259.815)', ...]

// With a custom theme
tw::colors('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');
// [..., 'brand' => '#3b82f6']

tw::breakpoints()

PHP

public static function breakpoints(string $css = '@import "tailwindcss";'): array

Возвращает все значения контрольных точек из темы. Возвращает array<string, string> (имя контрольной точки → значение).

PHP

use TailwindPHP\tw;

tw::breakpoints();
// ['sm' => '40rem', 'md' => '48rem', 'lg' => '64rem', 'xl' => '80rem', '2xl' => '96rem']

tw::breakpoints('@import "tailwindcss"; @theme { --breakpoint-xs: 20rem; }');
// ['sm' => '40rem', ..., '2xl' => '96rem', 'xs' => '20rem']

tw::spacing()

PHP

public static function spacing(string $css = '@import "tailwindcss";'): array

Возвращает пользовательские значения интервалов из темы. Возвращает array<string, string> (имя интервала → значение).

PHP

use TailwindPHP\tw;

// TailwindCSS 4 uses a single --spacing base value rather than a --spacing-* namespace.
// This returns any custom --spacing-* values defined in the theme.
tw::spacing('@import "tailwindcss"; @theme { --spacing-huge: 10rem; }');
// ['huge' => '10rem']

Форматы ввода

Методы просмотра (generate, properties, computedProperties, value, computedValue) принимают три формы ввода:

Формат	Пример
Только строка	`tw::generate('<div class="flex">')`
Строка + строка CSS	`tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')`
Массив с `content` (и необязательным `css`)	`tw::generate(['content' => '<div class="flex">', 'css' => '@import "tailwindcss";'])`

PHP

use TailwindPHP\tw;

// Format 1: string only
tw::properties('p-4');

// Format 2: string + CSS
tw::properties('bg-brand', '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

// Format 3: array
tw::properties(['content' => 'p-4', 'css' => '@import "tailwindcss";']);

Методы экземпляра TailwindCompiler

Объект, возвращаемый вызовом tw::compile(), предоставляет тот же интерфейс для просмотра, что и статический класс, и привязан к CSS, с которым он был скомпилирован. Используйте его, чтобы не разбирать тему при каждом вызове.

PHP

public function generate(string $content, bool $minify = false): string
public function css(array $candidates, bool $minify = false): string
public function generateExact(string $content, bool $minify = false): string
public function cssExact(array $candidates, bool $minify = false): string
public function extractCandidates(string $html): array
public function extractCandidatesFromStrings(string $source): array
public function properties(string|array $utilities): array
public function computedProperties(string|array $utilities): array
public function value(string $utility): ?string
public function computedValue(string $utility): ?string
public function minify(string $css): string
public function colors(): array
public function breakpoints(): array
public function spacing(): array

PHP

use TailwindPHP\tw;

$compiler = tw::compile('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }');

$css        = $compiler->generate('<div class="flex p-4 bg-brand">');
$candidates = $compiler->extractCandidates('<div class="flex p-4 bg-brand">');

$compiler->properties('bg-brand');          // ['background-color' => 'var(--color-brand)']
$compiler->computedProperties('bg-brand');   // ['background-color' => '#3b82f6']
$compiler->value('bg-brand');                // 'var(--color-brand)'
$compiler->computedValue('bg-brand');        // '#3b82f6'

$minified = $compiler->minify($css);

$compiler->colors();        // all color values
$compiler->breakpoints();   // all breakpoint values
$compiler->spacing();       // custom spacing values

Накопительная и точная генерация

generate() и css() накапливают данные: каждый вызов добавляет кандидатов в расширяющийся набор компилятора, а возвращаемая таблица стилей охватывает всё, что было обработано к этому моменту. Это подходит для единой таблицы стилей, создаваемой по шаблонам.

generateExact() и cssExact() при каждом вызове компилируют только заданное содержимое или кандидатов, не перенося данные между вызовами, но при этом повторно используют разобранную дизайн-систему компилятора. Результат совпадает с тем, который выдал бы холодный tw::generate() для того же содержимого. Это самый быстрый способ создавать CSS для отдельных страниц с помощью одного долго работающего компилятора:

PHP

use TailwindPHP\tw;

$compiler = tw::compile($themeCss);

foreach ($pages as $slug => $html) {
    $perPageCss[$slug] = $compiler->generateExact($html, true);
}

Все четыре метода принимают необязательный флаг $minify, который при сериализации создаёт минифицированный CSS, побайтно идентичный tw::generate(['minify' => true]) и более экономичный, чем минификация отформатированного результата после сериализации.

Расширенные инспекторы

Для непосредственного изучения скомпилированного состояния:

PHP

public function getTheme(): Theme
public function getDesignSystem(): object
public function getCompiled(): array

PHP

$compiler->getTheme();        // Theme object with resolved values
$compiler->getDesignSystem(); // Design system: utilities, variants, etc.
$compiler->getCompiled();     // Raw compiled state array

Эти методы возвращают внутренние структуры; их содержимое описано в разделе Архитектура.

Функции низкого уровня

Класс tw объединяет набор функций с пространствами имён в TailwindPHP. Они полезны, когда нужен необработанный результат компиляции, а не TailwindCompiler:

Функция	Назначение
`compile(string $css, array $options = []): array`	Разбирает и компилирует CSS. Возвращает `build` (с накоплением) и `buildExact` — замыкания, принимающие кандидатов и необязательный флаг `$minify`, — а также `sources`, `root`, `features` и `designSystem`. Принимает те же параметры, что и `tw::compile()`, кроме `stateCacheFile`
`StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array`	`compile()` с постоянным кэшем состояния компилятора
`parseCssState()`, `finalizeCssState()`, `compileParsed()`	Две части разбора (сериализуемое состояние, затем восстановленные из него замыкания) и финальный этап сборки, используемый `compileCssCached()`. `parseCss()` и `compileAst()` остаются эквивалентными функциями в один этап

PHP

use function TailwindPHP\compile;

$compiled = compile('@import "tailwindcss";');
$css = $compiled['build'](['flex', 'p-4'], true); // minified

Кэширование

tw::generate() может кэшировать скомпилированный CSS на диске, чтобы пропускать повторную компиляцию одинаковых входных данных.

Параметр	Тип	По умолчанию	Назначение
`cache`	`bool \| string`	`false`	`true` включает каталог по умолчанию; при передаче пути кэш сохраняется по нему
`cacheTtl`	`int`	нет	Срок хранения кэша в секундах; просроченные записи компилируются заново

PHP

use TailwindPHP\tw;

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

// Custom directory + TTL
$css = tw::generate([
    'content' => '<div class="flex p-4">',
    'cache' => '/path/to/cache',
    'cacheTtl' => 3600, // expire after 1 hour
]);

Ключ кэша формируется на основе содержимого, конфигурации CSS и параметра minify, поэтому для разных входных данных создаются разные файлы кэша. Удалите записи вызовом tw::clearCache() или отдельной функцией TailwindPHP\clearCache().

Подробнее см. в руководстве Кэширование и минификация.