# API Уся статична поверхня зосереджена в одному класі: `TailwindPHP\tw` (псевдонімі внутрішнього класу `Tailwind`). Кожен метод можна викликати статично, а методи інспекції (`properties`, `computedProperties`, `value`, `computedValue`) приймають усі описані внизу цієї сторінки [формати вводу](#input-formats). Для повторних операцій з тією самою конфігурацією CSS викличте [`tw::compile()`](#twcompile) один раз і повторно використовуйте повернений [`TailwindCompiler`](#tailwindcompiler-instance-methods). ```php use TailwindPHP\tw; $css = tw::generate('
'); ``` ## 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('
'); // String with custom CSS $css = tw::generate('
', '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }'); // Array input with options $css = tw::generate([ 'content' => '
', 'css' => '@import "tailwindcss";', 'minify' => true, ]); ``` Форма з масивом приймає такі ключі: | Ключ | Тип | Призначення | |---|---|---| | `content` | `string` | Вміст для пошуку кандидатів класів (обов’язково) | | `css` | `string` | Вхідний CSS із директивами Tailwind (типово `@import "tailwindcss";`) | | `minify` | `bool` | Мінімізувати результат (типово `false`) | | `importPaths` | `string \| array \| callable \| null` | Завантажувати CSS із файлової системи з повним розв’язанням `@import` — див. [Імпорт CSS](https://tailwindphp.inline0.dev/uk/docs/usage/imports) | | `cache` | `bool \| string` | Увімкнути кешування файлів — див. [Кешування](#caching) | | `cacheTtl` | `int` | Час життя кешу в секундах | ## tw::compile() ```php public static function compile(string $css = '@import "tailwindcss";', array $options = []): TailwindCompiler ``` Створює багаторазово використовуваний `TailwindCompiler`, прив’язаний до заданої конфігурації CSS. Розбір і створення дизайн-системи виконуються один раз, тож це ефективний варіант для генерування CSS для багатьох різних рядків вмісту. Використовуйте `generate()`, щоб накопичувати одну таблицю стилів між викликами, або [`generateExact()`](#accumulating-vs-exact-generation) для незалежного результату для кожної сторінки. **Повертає** `TailwindCompiler`. ```php use TailwindPHP\tw; // Default Tailwind $compiler = tw::compile(); // Custom CSS $compiler = tw::compile('@import "tailwindcss"; @theme { --color-brand: #3b82f6; }'); $css = $compiler->generate('
'); ``` Масив `$options` приймає: | Параметр | Тип | Призначення | |---|---|---| | `stateCacheFile` | `string` | Шлях до файлу PHP, який зберігає стан побудови компілятора між запитами й процесами — див. [Кеш стану компілятора](https://tailwindphp.inline0.dev/uk/docs/advanced/caching#compiler-state-cache) | | `polyfills` | `int` | Визначає резервні значення для виведення як бітову маску з `TailwindPHP\POLYFILL_AT_PROPERTY` (типові `@layer properties` для змінних `@property`) і `TailwindPHP\POLYFILL_COLOR_MIX` (статичні резервні значення кольорів перед `color-mix()`). Типово `POLYFILL_ALL`; `POLYFILL_NONE` вимикає обидва варіанти | | `importSearchPaths` | `array` | Каталоги для пошуку `@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('
'); // .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](#tailwindcompiler-instance-methods). ## tw::properties() ```php public static function properties(string|array $input, string $css = '@import "tailwindcss";'): array ``` Повертає **необроблені** властивості CSS для класу, залишаючи змінні CSS нерозв’язаними. **Повертає** `array` (назва властивості → значення). ```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()`](#twproperties), але з усіма змінними CSS, розв’язаними до конкретних значень. **Повертає** `array`. ```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`. ```php use TailwindPHP\tw; tw::extractCandidates('
'); // ['flex', 'p-4', 'bg-blue-500'] ``` ## tw::extractCandidatesFromStrings() ```php public static function extractCandidatesFromStrings(string $source): array ``` Витягує потенційні назви класів з кожного рядка в одинарних або подвійних лапках у вихідному коді. Це призначено для шаблонів, де списки класів формуються у змінних, а не в атрибутах `class`. Кожен рядок розбивається за пробілами, і зберігаються всі фрагменти, схожі на назви класів. **Повертає** `array`. ```php use TailwindPHP\tw; $classes = tw::extractCandidatesFromStrings(''); // ['p-4', 'sm:flex', 'hello', 'world'] $css = tw::compile()->css($classes); ``` Звичайні слова також проходять перевірку (`hello`, `world` вище); вони нічого не компілюють, якщо випадково не є назвами утиліт. Передайте результат у [`css()`](#tailwindcompiler-instance-methods), оскільки `generate()` читає лише атрибути `class`. ## tw::cssMap() ```php public static function cssMap(string $css = '@import "tailwindcss";'): array ``` Створює зворотну мапу від оголошень CSS до класів утиліт; вона стане в пригоді для перетворення наявного CSS на класи Tailwind. Ключі — рядки `"property: value"` із розв’язаними змінними (утиліти з кількома властивостями також отримують ключ `"prop: value; prop: value"`), значення — назви класів. **Повертає** `array`. ```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` у [методах компілятора](#tailwindcompiler-instance-methods). Такий спосіб мінімізує під час серіалізації, що швидше й зберігає дочірні селектори `:not()`, які згортає обробка рядка. ```php use TailwindPHP\tw; $css = tw::generate('
'); $minified = tw::minify($css); ``` Повний перелік оптимізацій див. у розділі [Кешування та мінімізація](https://tailwindphp.inline0.dev/uk/docs/advanced/caching). ## 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` (назва кольору → обчислене значення). ```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` (назва контрольної точки → значення). ```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` (назва інтервалу → значення). ```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('
')` | | Рядок + рядок CSS | `tw::generate('
', '@import "tailwindcss"; @theme { ... }')` | | Масив із `content` (+ необов’язковий `css`) | `tw::generate(['content' => '
', '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()`](#twcompile), надає ті самі можливості інспекції, що й статичний клас, і прив’язаний до 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('
'); $candidates = $compiler->extractCandidates('
'); $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 ``` Вони повертають внутрішні структури; їхній вміст описано в розділі [Архітектура](https://tailwindphp.inline0.dev/uk/docs/advanced/architecture). ### Функції нижчого рівня Клас `tw` обгортає набір функцій із просторами імен у `TailwindPHP`. Вони стануть у пригоді, коли потрібен необроблений результат компіляції, а не `TailwindCompiler`: | Функція | Призначення | |---|---| | `compile(string $css, array $options = []): array` | Розбирає та компілює CSS. Повертає `build` (накопичувальні) і замикання `buildExact`, які приймають кандидатів і необов’язковий прапорець `$minify`, а також `sources`, `root`, `features` і `designSystem`. Приймає ті самі параметри, що й [`tw::compile()`](#twcompile), крім `stateCacheFile` | | `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | `compile()` із постійним [кешем стану компілятора](https://tailwindphp.inline0.dev/uk/docs/advanced/caching#compiler-state-cache) | | `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' => '
', 'cache' => true, ]); // Custom directory + TTL $css = tw::generate([ 'content' => '
', 'cache' => '/path/to/cache', 'cacheTtl' => 3600, // expire after 1 hour ]); ``` Ключ кешу визначається на основі **вмісту**, **конфігурації CSS** та параметра **мінімізації**, тож для різних входів створюються різні файли кешу. Очистіть записи за допомогою [`tw::clearCache()`](#twclearcache) або окремої функції `TailwindPHP\clearCache()`. Докладніші відомості див. в посібнику [Кешування та мінімізація](https://tailwindphp.inline0.dev/uk/docs/advanced/caching).