API

Wyświetl jako Markdown Edytuj w GitHub Dokumentacja: 3843abd

Cały statyczny interfejs znajduje się w jednej klasie: TailwindPHP\tw (alias wewnętrznej klasy Tailwind). Każdą metodę można wywołać statycznie, a metody inspekcji (properties, computedProperties, value, computedValue) przyjmują formaty wejściowe opisane na dole tej strony: formaty wejściowe.

Przy powtarzanej pracy z tą samą konfiguracją CSS wywołaj raztw::compile() i używaj ponownie zwróconego wynikuTailwindCompiler.

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

Analizuje treść, wyodrębnia kandydatów na klasy i zwraca wygenerowany CSS. Domyślny $css to @import "tailwindcss";, który uwzględnia motyw, preflight i utilities. Zwraca 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 tablicowa przyjmuje następujące klucze:

Klucz	Typ	Przeznaczenie
`content`	`string`	Treść do skanowania w poszukiwaniu kandydatów na klasy (wymagane)
`css`	`string`	Wejściowy CSS z dyrektywami Tailwind (domyślnie `@import "tailwindcss";`)
`minify`	`bool`	Minifikacja wyniku (domyślnie `false`)
`importPaths`	`string \| array \| callable \| null`	Ładowanie CSS z systemu plików z pełnym rozwiązywaniem `@import` — zobacz Importowanie CSS
`cache`	`bool \| string`	Włączenie buforowania plików — zobacz Buforowanie
`cacheTtl`	`int`	Czas życia pamięci podręcznej w sekundach

tw::compile()

PHP

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

Tworzy wielokrotnego użytku TailwindCompiler powiązane z podanym CSS. Parsowanie i tworzenie systemu projektowego odbywają się raz, dlatego jest to wydajny wybór przy generowaniu CSS dla wielu różnych ciągów treści. Użyj generate(), aby gromadzić jeden arkusz stylów między wywołaniami, albo generateExact(), aby uzyskać niezależny wynik dla każdej strony. Zwraca 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">');

Tablica $options przyjmuje:

Opcja	Typ	Przeznaczenie
`stateCacheFile`	`string`	Ścieżka do pliku PHP, który zachowuje stan konstrukcji kompilatora między żądaniami i procesami — zobacz Pamięć podręczna stanu kompilatora
`polyfills`	`int`	Określa emitowane wartości zastępcze jako maskę bitową `TailwindPHP\POLYFILL_AT_PROPERTY` (wartości domyślne `@layer properties` dla zmiennych `@property`) oraz `TailwindPHP\POLYFILL_COLOR_MIX` (statyczne wartości zastępcze kolorów przed `color-mix()`). Domyślnie `POLYFILL_ALL`; `POLYFILL_NONE` wyłącza obie opcje
`importSearchPaths`	`array<string>`	Katalogi przeszukiwane podczas rozwiązywania `@import` z systemu plików

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)

Pełny zestaw metod instancji opisano w sekcji Metody instancji TailwindCompiler.

tw::properties()

PHP

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

Zwraca surowe właściwości CSS dla klasy, pozostawiając nierozwiązane zmienne CSS. Zwraca array<string, string> (nazwa właściwości → wartość).

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

Podobnie jak properties(), ale rozwiązuje każdą zmienną CSS do konkretnej wartości. Zwraca 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

Zwraca surową wartość dla pojedynczej klasy utility. Zwraca ?string — null, jeśli utility nie zostanie znalezione.

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

Zwraca rozwiązaną wartość dla pojedynczej klasy utility. Zwraca ?string — null, jeśli utility nie zostanie znalezione.

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

Wyodrębnia nazwy klas Tailwind z treści (odczytuje atrybuty class i className). Zwraca 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

Wyodrębnia kandydatów na nazwy klas z każdego ciągu ujętego w pojedynczy lub podwójny cudzysłów w kodzie źródłowym. Przydaje się w szablonach, które budują listy klas w zmiennych zamiast w atrybutach class. Każdy ciąg jest dzielony według białych znaków, a każdy token przypominający nazwę klasy zostaje zachowany. Zwraca 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);

Zwykłe słowa również przechodzą kontrolę (hello, world powyżej); kompilują się do pustego wyniku, chyba że przypadkiem są nazwami utility. Przekaż wynik do css(), ponieważ generate() odczytuje tylko atrybuty class.

tw::cssMap()

PHP

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

Buduje mapę odwrotną od deklaracji CSS do klas utility, przydatną do konwertowania istniejącego CSS na klasy Tailwind. Kluczami są ciągi "property: value" z rozwiązanymi zmiennymi (utility z wieloma właściwościami otrzymują również klucz "prop: value; prop: value"), a wartościami są nazwy klas. Zwraca 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 obejmuje stałą listę popularnych utility (wyświetlanie, pozycjonowanie, flexbox, typografia, odstępy i rozmiary, obramowania, kolory czarny, biały i przezroczysty oraz podobne), a nie wszystkie utility czy kolory motywu. Argument $css zmienia rozwiązane wartości tych utility, ale własne tokeny motywu (takie jak --color-brand) nie dodają wpisów.

tw::minify()

PHP

public static function minify(string $css): string

Minifikuje dowolny ciąg CSS: usuwa komentarze, redukuje białe znaki, skraca kolory szesnastkowe (#ffffff → #fff), usuwa jednostki od wartości zerowych (0px → 0) i robi więcej. Zwraca string.

W przypadku CSS generowanego przez samo TailwindPHP lepiej użyć opcji minify (tw::generate(['minify' => true])) lub parametru $minify w metodach kompilatora. Ta ścieżka minifikuje podczas serializacji, co jest szybsze i zachowuje selektory potomków :not(), które przebieg oparty na ciągu znaków scala.

PHP

use TailwindPHP\tw;

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

Pełny zestaw optymalizacji opisano w sekcji Buforowanie i minifikacja.

tw::clearCache()

PHP

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

Usuwa pliki CSS z pamięci podręcznej. Przekaż true (lub pomiń), aby użyć domyślnego katalogu pamięci podręcznej, albo ciąg ze ścieżką do katalogu niestandardowego. Zwraca int — liczbę usuniętych plików.

PHP

use TailwindPHP\tw;

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

Dostępna jest również samodzielna funkcja TailwindPHP\clearCache().

tw::colors()

PHP

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

Zwraca wszystkie wartości kolorów z motywu. Zwraca array<string, string> (nazwa koloru → obliczona wartość).

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

Zwraca wszystkie wartości punktów przerwania z motywu. Zwraca array<string, string> (nazwa punktu przerwania → wartość).

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

Zwraca niestandardowe wartości odstępów z motywu. Zwraca array<string, string> (nazwa odstępu → wartość).

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

Formaty wejściowe

Metody inspekcji (generate, properties, computedProperties, value, computedValue) akceptują trzy formy wejścia:

Format	Przykład
Tylko ciąg znaków	`tw::generate('<div class="flex">')`
Ciąg znaków + ciąg CSS	`tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')`
Tablica z `content` (+ opcjonalne `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";']);

Metody instancji TailwindCompiler

Obiekt zwracany przez tw::compile() udostępnia ten sam zestaw metod inspekcji co klasa statyczna, powiązany z CSS, z którym został skompilowany. Użyj go, aby uniknąć ponownego parsowania motywu przy każdym wywołaniu.

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

Generowanie narastające a dokładne

generate() i css() gromadzą dane: każde wywołanie dodaje swoich kandydatów do rosnącego zbioru kompilatora, a zwracany arkusz stylów obejmuje wszystko, co dotąd napotkano. Sprawdza się to w przypadku jednego arkusza stylów budowanego na podstawie kolejnych szablonów.

generateExact() i cssExact() kompilują przy każdym wywołaniu dokładnie podaną treść lub kandydatów, bez przenoszenia danych między wywołaniami, a jednocześnie ponownie wykorzystują sparsowany system projektowy kompilatora. Wynik odpowiada temu, co wygenerowałoby świeże tw::generate() dla tej samej treści. To najszybszy sposób tworzenia CSS dla poszczególnych stron za pomocą jednego długo działającego kompilatora:

PHP

use TailwindPHP\tw;

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

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

Wszystkie cztery metody akceptują opcjonalną flagę $minify, która podczas serializacji emituje zminifikowane CSS, identyczne bajt w bajt z tw::generate(['minify' => true]) i tańsze niż późniejsza minifikacja czytelnego wyniku.

Zaawansowane inspektory

Bezpośrednia inspekcja skompilowanego stanu:

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

Zwracają one struktury wewnętrzne; informacje o ich zawartości znajdziesz w sekcji Architektura.

Funkcje niższego poziomu

Klasa tw opakowuje zestaw funkcji z przestrzeni nazw TailwindPHP. Przydają się, gdy potrzebujesz surowego wyniku kompilacji zamiast TailwindCompiler:

Funkcja	Przeznaczenie
`compile(string $css, array $options = []): array`	Parsuje i kompiluje CSS. Zwraca `build` (narastająco) oraz domknięcia `buildExact`, które przyjmują kandydatów i opcjonalną flagę `$minify`, a także `sources`, `root`, `features` i `designSystem`. Przyjmuje te same opcje co `tw::compile()`, z wyjątkiem `stateCacheFile`
`StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array`	`compile()` z trwałą pamięcią podręczną stanu kompilatora
`parseCssState()`, `finalizeCssState()`, `compileParsed()`	Dwie części parsowania (stan możliwy do serializacji, a następnie odtworzone na jego podstawie domknięcia) oraz końcowy etap składania używany przez `compileCssCached()`. `parseCss()` i `compileAst()` pozostają odpowiednikami wykonującymi te czynności w jednym kroku

PHP

use function TailwindPHP\compile;

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

Buforowanie

tw::generate() może zapisywać skompilowane CSS na dysku w pamięci podręcznej, aby identyczne dane wejściowe pomijały ponowną kompilację.

Opcja	Typ	Domyślnie	Przeznaczenie
`cache`	`bool \| string`	`false`	`true` włącza domyślny katalog; ciąg ze ścieżką wskazuje miejsce zapisu w pamięci podręcznej
`cacheTtl`	`int`	brak	Czas życia pamięci podręcznej w sekundach; wygasłe wpisy są kompilowane ponownie

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

Klucz pamięci podręcznej jest wyprowadzany z treści, konfiguracji CSS i opcji minify, dlatego różne dane wejściowe tworzą różne pliki pamięci podręcznej. Wyczyść wpisy za pomocą tw::clearCache() lub samodzielnej funkcji TailwindPHP\clearCache().

Szczegółowe omówienie znajdziesz w sekcji Buforowanie i minifikacja.