API

Zobrazit jako Markdown Upravit na GitHub Dokumentace na 3843abd

Celé statické rozhraní je dostupné na jedné třídě: TailwindPHP\tw (alias interní třídy Tailwind). Každou metodu lze volat staticky a inspekční metody (properties, computedProperties, value, computedValue) přijímají vstupní formáty popsané na konci této stránky.

Při opakované práci se stejnou konfigurací CSS zavolejte jednou tw::compile() a vrácenou TailwindCompiler znovu použijte.

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áty tříd a vrací vygenerované CSS. Výchozí $css je @import "tailwindcss";, které zahrnuje motiv, preflight a nástroje. Vrací 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,
]);

Pole přijímá následující klíče:

Klíč	Typ	Účel
`content`	`string`	Obsah ke skenování pro kandidáty tříd (povinné)
`css`	`string`	Vstup CSS s direktivami Tailwind (výchozí `@import "tailwindcss";`)
`minify`	`bool`	Minifikace výstupu (výchozí `false`)
`importPaths`	`string \| array \| callable \| null`	Načtení CSS ze souborového systému s úplným rozlišením `@import` — viz Import CSS
`cache`	`bool \| string`	Povolení ukládání souborů do mezipaměti — viz Ukládání do mezipaměti
`cacheTtl`	`int`	Doba platnosti mezipaměti v sekundách

tw::compile()

PHP

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

Vytvoří opakovaně použitelný TailwindCompiler navázaný na zadané CSS. Analýza a sestavení návrhového systému proběhnou pouze jednou, takže jde o efektivní volbu při generování CSS pro mnoho různých řetězců obsahu. Pomocí generate() můžete napříč voláními postupně sestavovat jeden stylopis, nebo použijte generateExact() pro nezávislý výstup každé stránky. Vrací 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 přijímá:

Možnost	Typ	Účel
`stateCacheFile`	`string`	Cesta k souboru PHP, který uchovává stav sestavení kompilátoru mezi požadavky a procesy — viz Mezipaměť stavu kompilátoru
`polyfills`	`int`	Které záložní hodnoty generovat jako bitovou masku `TailwindPHP\POLYFILL_AT_PROPERTY` (`@layer properties` pro proměnné `@property`) a `TailwindPHP\POLYFILL_COLOR_MIX` (statické záložní hodnoty barev před `color-mix()`). Výchozí `POLYFILL_ALL`; `POLYFILL_NONE` obě vypne
`importSearchPaths`	`array<string>`	Adresáře, ve kterých hledat při rozpoznávání `@import` ze souborové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ý přehled metod instance najdete v části Metody instance TailwindCompiler.

tw::properties()

PHP

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

Vrací nezpracované vlastnosti CSS pro třídu, přičemž proměnné CSS ponechává nevyřešené. Vrací array<string, string> (název 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

Podobně jako properties(), ale každá proměnná CSS je převedena na konkrétní hodnotu. Vrací 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

Vrací nezpracovanou hodnotu jedné pomocné třídy. Vrací ?string — null, pokud pomocná třída nebyla nalezena.

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

Vrací vyřešenou hodnotu jedné pomocné třídy. Vrací ?string — null, pokud pomocná třída nebyla nalezena.

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 tříd Tailwind z obsahu (čte atributy class i className). Vrací 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áty názvů tříd ze všech řetězců v jednoduchých nebo dvojitých uvozovkách ve zdrojovém kódu; hodí se pro šablony, které sestavují seznamy tříd v proměnných místo v atributech class. Každý řetězec se rozdělí podle mezer a ponechá se každý token, který vypadá jako název třídy. Vrací 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 projdou i obyčejná slova (hello, world výše); zkompilují se na prázdný výstup, pokud náhodou nejde o názvy pomocných tříd. Výsledek předejte funkci css(), protože generate() čte pouze atributy class.

tw::cssMap()

PHP

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

Vytvoří zpětnou mapu z deklarací CSS na pomocné třídy, která se hodí při převodu stávajícího CSS na třídy Tailwind. Klíče jsou řetězce "property: value" s vyřešenými proměnnými (u pomocných tříd s více vlastnostmi se přidá také klíč "prop: value; prop: value"); hodnotami jsou názvy tříd. Vrací 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 zahrnuje pevný seznam běžných pomocných tříd (zobrazení, pozice, flexbox, typografie, kroky mezer a rozměrů, okraje, černá, bílá a průhledná barva a podobně), nikoli všechny pomocné třídy nebo barvy motivu. Argument $css mění vyřešené hodnoty těchto tříd, ale vlastní tokeny motivu (například --color-brand) nepřidávají položky.

tw::minify()

PHP

public static function minify(string $css): string

Minifikuje libovolný řetězec CSS: odstraní komentáře, sloučí bílé znaky, zkrátí šestnáctkové barvy (#ffffff → #fff), odebere jednotky od nulových hodnot (0px → 0) a provede další úpravy. Vrací string.

U CSS, který TailwindPHP generuje samo, použijte raději možnost minify (tw::generate(['minify' => true])) nebo parametr $minify u metod kompilátoru. Tímto způsobem se minifikace provede při serializaci, která je rychlejší a zachovává potomkové selektory :not(), jež průchod založený na řetězcích sloučí.

PHP

use TailwindPHP\tw;

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

Úplný přehled optimalizací najdete v části Ukládání do mezipaměti a minifikace.

tw::clearCache()

PHP

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

Odstraní soubory CSS z mezipaměti. Předejte true (nebo jej vynechte), chcete-li použít výchozí adresář mezipaměti, případně řetězec s vlastní cestou. Vrací int — počet odstraněných souborů.

PHP

use TailwindPHP\tw;

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

K dispozici je také samostatná funkce TailwindPHP\clearCache().

tw::colors()

PHP

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

Vrací všechny barevné hodnoty z motivu. Vrací array<string, string> (název barvy → vypočtená 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

Vrací všechny hodnoty zlomů rozvržení z motivu. Vrací array<string, string> (název 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

Vrací vlastní hodnoty mezer z motivu. Vrací array<string, string> (název mezery → 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

Inspekční metody (generate, properties, computedProperties, value, computedValue) přijímají tři formy vstupu:

Formát	Příklad
Pouze řetězec	`tw::generate('<div class="flex">')`
Řetězec + řetězec CSS	`tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')`
Pole s `content` (+ volitelně `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 instance TailwindCompiler

Objekt vrácený funkcí tw::compile() zpřístupňuje stejné inspekční metody jako statická třída, navázané na CSS, se kterým byl zkompilován. Použijte jej, abyste nemuseli při každém volání znovu analyzovat motiv.

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é sestavování a přesné generování

generate() a css() postupně přidávají: každé volání přidá své kandidáty do průběžně se rozšiřující sady kompilátoru a vrácený stylopis zahrnuje vše, co se dosud zpracovalo. Hodí se pro jeden stylopis sestavovaný napříč šablonami.

generateExact() a cssExact() při každém volání kompilují přesně zadaný obsah nebo kandidáty, bez přenášení výsledků z předchozích volání, a přitom znovu používají již analyzovaný návrhový systém kompilátoru. Výstup odpovídá tomu, co by vytvořila nová kompilace tw::generate() se stejným obsahem. Jde o nejrychlejší způsob, jak z jedné dlouho běžící instance kompilátoru vytvořit CSS pro jednotlivé stránky:

PHP

use TailwindPHP\tw;

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

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

Všechny čtyři metody přijímají volitelný příznak $minify, který při serializaci vytváří minifikované CSS. Výsledek je po bajtech totožný s tw::generate(['minify' => true]) a jeho vytvoření stojí méně než následná minifikace formátovaného výstupu.

Pokročilé inspektory

Pro přímou kontrolu zkompilované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

Tyto metody vracejí interní struktury; jejich obsah popisuje Architektura.

Funkce nižší úrovně

Třída tw obaluje sadu funkcí v jmenném prostoru TailwindPHP. Hodí se, když potřebujete nezpracovaný výsledek kompilace místo TailwindCompiler:

Funkce	Účel
`compile(string $css, array $options = []): array`	Analyzuje a kompiluje CSS. Vrací uzávěry `build` (postupné přidávání) a `buildExact`, které přijímají kandidáty a volitelný příznak `$minify`, a také `sources`, `root`, `features` a `designSystem`. Přijímá stejné možnosti jako `tw::compile()`, kromě `stateCacheFile`
`StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array`	`compile()` s trvalou mezipamětí stavu kompilátoru
`parseCssState()`, `finalizeCssState()`, `compileParsed()`	Dvě části analýzy (serializovatelný stav a následně z něj znovu sestavené uzávěry) a závěrečný krok sestavení, který používá `compileCssCached()`. `parseCss()` a `compileAst()` zůstávají jejich jednorázovými ekvivalenty

PHP

use function TailwindPHP\compile;

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

Ukládání do mezipaměti

tw::generate() může ukládat zkompilované CSS na disk, takže se shodné vstupy nemusejí znovu kompilovat.

Možnost	Typ	Výchozí hodnota	Účel
`cache`	`bool \| string`	`false`	`true` povolí výchozí adresář; řetězec s cestou určuje místo ukládání do mezipaměti
`cacheTtl`	`int`	žádná	Doba platnosti mezipaměti v sekundách; po jejím vypršení se položky znovu kompilují

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

Klíč mezipaměti se odvozuje od obsahu, konfigurace CSS a možnosti minify, takže různé vstupy vytvářejí různé soubory mezipaměti. Položky vymažete pomocí tw::clearCache() nebo samostatné funkce TailwindPHP\clearCache().

Podrobnější průvodce najdete v části Ukládání do mezipaměti a minifikace.