API

Zobraziť ako Markdown Upraviť na GitHub Dokumentácia na 3843abd

Celé statické rozhranie je sústredené v jednej triede: TailwindPHP\tw (alias internej triedy Tailwind). Každú metódu možno volať staticky a kontrolné metódy (properties, computedProperties, value, computedValue) prijímajú všetky vstupné formáty opísané na konci tejto stránky.

Ak opakovane pracujete s rovnakou konfiguráciou CSS, raz zavolajte tw::compile() a vrátenú hodnotu TailwindCompiler používajte opakovane.

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

Analyzuje obsah, extrahuje kandidátov na triedy a vracia vygenerované CSS. Predvolená hodnota $css je @import "tailwindcss";, ktorá načíta tému, preflight a utility. Vracia 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,
]);

Forma s poľom prijíma tieto kľúče:

Kľúč	Typ	Účel
`content`	`string`	Obsah, v ktorom sa hľadajú kandidáti na triedy (povinné)
`css`	`string`	Vstup CSS s direktívami Tailwind (predvolené `@import "tailwindcss";`)
`minify`	`bool`	Minifikácia výstupu (predvolené `false`)
`importPaths`	`string \| array \| callable \| null`	Načítanie CSS zo súborového systému s úplným rozlíšením `@import` — pozrite si časť Importovanie CSS
`cache`	`bool \| string`	Zapnutie cachovania súborov — pozrite si časť Cachovanie
`cacheTtl`	`int`	Životnosť cache v sekundách

tw::compile()

PHP

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

Vytvorí opakovane použiteľný TailwindCompiler naviazaný na zadanú hodnotu CSS. Analýza a zostavenie systému návrhu sa vykonajú raz. Je to preto efektívna voľba pri generovaní CSS pre mnoho rôznych reťazcov obsahu. Pomocou generate() môžete v jednotlivých volaniach postupne dopĺňať jeden štýlový hárok alebo pomocou generateExact() vytvárať nezávislý výstup pre každú stránku. Vracia 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">');

Pole $options prijíma:

Možnosť	Typ	Účel
`stateCacheFile`	`string`	Cesta k súboru PHP, ktorý uchováva stav zostavenia kompilátora medzi požiadavkami a procesmi — pozrite si časť Cache stavu kompilátora
`polyfills`	`int`	Ktoré záložné hodnoty vytvoriť, ako bitovú masku hodnôt `TailwindPHP\POLYFILL_AT_PROPERTY` (predvolené hodnoty `@layer properties` pre premenné `@property`) a `TailwindPHP\POLYFILL_COLOR_MIX` (statické záložné farby pred `color-mix()`). Predvolená hodnota `POLYFILL_ALL`; `POLYFILL_NONE` vypne obe možnosti
`importSearchPaths`	`array<string>`	Adresáre, v ktorých sa hľadá `@import` pri načítaní zo súborového systému

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)

Úplný prehľad metód inštancie nájdete v časti Metódy inštancie TailwindCompiler.

tw::properties()

PHP

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

Vracia nespracované vlastnosti CSS pre triedu, pričom premenné CSS ponecháva nevyriešené. Vracia array<string, string> (názov vlastnosti → hodnota).

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

Podobne ako properties(), ale každá premenná CSS je rozriešená na konkrétnu hodnotu. Vracia 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

Vracia nespracovanú hodnotu pre jednu triedu utility. Vracia ?string — null, ak sa utilita nenájde.

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

Vracia rozriešenú hodnotu pre jednu triedu utility. Vracia ?string — null, ak sa utilita nenájde.

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

Extrahuje názvy tried Tailwind z obsahu (číta atribúty class aj className). Vracia 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

Extrahuje kandidátov na názvy tried z každého reťazca v jednoduchých alebo dvojitých úvodzovkách v zdrojovom kóde. Je určená pre šablóny, ktoré vytvárajú zoznamy tried v premenných namiesto atribútov class. Každý reťazec sa rozdelí podľa medzier a ponechajú sa všetky tokeny, ktoré vyzerajú ako názvy tried. Vracia 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);

Kontrolou prejdú aj obyčajné slová (vyššie uvedené hello, world); nepreložia sa na nič, pokiaľ náhodou nejde o názvy utilít. Výsledok odovzdajte do css(), pretože generate() číta iba atribúty class.

tw::cssMap()

PHP

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

Vytvorí spätnú mapu deklarácií CSS na triedy utilít, ktorá je užitočná pri prevode existujúcich CSS na triedy Tailwind. Kľúčmi sú reťazce "property: value" s rozriešenými premennými (utility s viacerými vlastnosťami získajú aj kľúč "prop: value; prop: value"), hodnotami sú názvy tried. Vracia 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'

Mapa pokrýva pevný zoznam bežných utilít (zobrazenie, pozícia, flexbox, typografia, kroky rozostupov a veľkostí, okraje, čierna/biela/priehľadná farba a podobne), nie všetky utility ani farby témy. Argument $css mení rozriešené hodnoty týchto utilít, ale vlastné tokeny témy (napríklad --color-brand) nepridávajú ďalšie položky.

tw::minify()

PHP

public static function minify(string $css): string

Minifikuje ľubovoľný reťazec CSS: odstraňuje komentáre, zlučuje medzery, skracuje hexadecimálne farby (#ffffff → #fff), odstraňuje jednotky z nulových hodnôt (0px → 0) a podobne. Vracia string.

Pri CSS, ktoré TailwindPHP generuje samo, uprednostnite možnosť minify (tw::generate(['minify' => true])) alebo parameter $minify metód kompilátora. Pri tomto postupe sa výstup minifikuje počas serializácie, čo je rýchlejšie a zachováva vnorené selektory :not(), ktoré priechod založený na reťazcoch zlúči.

PHP

use TailwindPHP\tw;

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

Úplný zoznam optimalizácií nájdete v časti Cachovanie a minifikácia.

tw::clearCache()

PHP

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

Odstráni súbory CSS z cache. Ak chcete použiť predvolený adresár cache, zadajte true alebo tento parameter vynechajte; pre vlastný adresár zadajte cestu. Vracia int — počet odstránených súborov.

PHP

use TailwindPHP\tw;

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

K dispozícii je aj samostatná funkcia TailwindPHP\clearCache().

tw::colors()

PHP

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

Vracia všetky hodnoty farieb z témy. Vracia array<string, string> (názov farby → vypočítaná hodnota).

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

Vracia všetky hodnoty bodov zlomu z témy. Vracia array<string, string> (názov bodu zlomu → hodnota).

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

Vracia vlastné hodnoty rozostupov z témy. Vracia array<string, string> (názov rozostupu → hodnota).

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']

Vstupné formáty

Kontrolné metódy (generate, properties, computedProperties, value, computedValue) prijímajú tri formy vstupu:

Formát	Príklad
Iba reťazec	`tw::generate('<div class="flex">')`
Reťazec + reťazec CSS	`tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')`
Pole s `content` (+ voliteľne `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";']);

Metódy inštancie TailwindCompiler

Objekt vrátený volaním tw::compile() poskytuje rovnaké kontrolné rozhranie ako statická trieda a je naviazaný na hodnotu CSS, s ktorou bol skompilovaný. Použite ho, aby ste pri každom volaní nemuseli znova analyzovať tému.

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

Postupné a presné generovanie

generate() a css() postupne zhromažďujú kandidátov: každé volanie pridá kandidátov do rastúcej množiny kompilátora a vrátený štýlový hárok pokrýva všetko, čo sa dovtedy spracovalo. Hodí sa to na zostavenie jedného štýlového hárka z viacerých šablón.

generateExact() a cssExact() pri každom volaní kompilujú zadaný obsah alebo kandidátov presne, bez prenášania medzi volaniami, pričom naďalej opakovane používajú analyzovaný systém návrhu kompilátora. Výstup zodpovedá tomu, čo by vytvorila nová kompilácia tw::generate() rovnakého obsahu. Toto je najrýchlejší spôsob, ako vytvárať CSS pre jednotlivé stránky pomocou jedného dlho žijúceho kompilátora:

PHP

use TailwindPHP\tw;

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

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

Všetky štyri metódy prijímajú voliteľný príznak $minify, ktorý pri serializácii vytvorí minifikované CSS. Výsledok je bajtovo totožný s tw::generate(['minify' => true]) a jeho vytvorenie je úspornejšie než dodatočná minifikácia formátovaného výstupu.

Pokročilé kontrolné nástroje

Na priame preskúmanie skompilovaného stavu:

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

Vracajú interné štruktúry; ich obsah nájdete v časti Architektúra.

Funkcie nižšej úrovne

Trieda tw obaluje skupinu funkcií s vlastnými názvami v TailwindPHP. Sú užitočné, keď potrebujete nespracovaný výsledok kompilácie namiesto hodnoty TailwindCompiler:

Funkcia	Účel
`compile(string $css, array $options = []): array`	Analyzuje a kompiluje CSS. Vracia `build` (postupne zhromažďujúce) a uzávery `buildExact`, ktoré prijímajú kandidátov a voliteľný príznak `$minify`, ako aj `sources`, `root`, `features` a `designSystem`. Prijíma rovnaké možnosti ako `tw::compile()`, okrem `stateCacheFile`
`StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array`	`compile()` s trvalou cache stavu kompilátora
`parseCssState()`, `finalizeCssState()`, `compileParsed()`	Dve fázy analýzy (serializovateľný stav, potom z neho znovu zostavené uzávery) a záverečný krok zostavenia, ktorý používa `compileCssCached()`. `parseCss()` a `compileAst()` zostávajú ich jedno-krokovými ekvivalentmi

PHP

use function TailwindPHP\compile;

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

Ukladanie do vyrovnávacej pamäte

tw::generate() môže ukladať skompilované CSS na disk, aby sa pri rovnakých vstupoch preskočila opätovná kompilácia.

Možnosť	Typ	Predvolené	Účel
`cache`	`bool \| string`	`false`	`true` zapne predvolený adresár; reťazec s cestou určí adresár cache
`cacheTtl`	`int`	none	Životnosť cache v sekundách; položky po uplynutí platnosti sa skompilujú znova

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
]);

Kľúč cache sa odvodzuje od obsahu, konfigurácie CSS a možnosti minify, takže rôzne vstupy vytvárajú rôzne súbory cache. Položky odstránite pomocou tw::clearCache() alebo samostatnej funkcie TailwindPHP\clearCache().

Podrobnejší návod nájdete v časti Cachovanie a minifikácia.