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'

Мапа охоплює фіксований перелік поширених утиліт (відображення, позиціювання, 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 та параметра мінімізації, тож для різних входів створюються різні файли кешу. Очистіть записи за допомогою tw::clearCache() або окремої функції TailwindPHP\clearCache().

Докладніші відомості див. в посібнику Кешування та мінімізація.