API

Visualizza come Markdown Modifica su GitHub Documentazione di 3843abd

Tutta l'API statica è disponibile in un'unica classe: TailwindPHP\tw (alias della classe interna Tailwind). Ogni metodo è richiamabile staticamente e i metodi di ispezione (properties, computedProperties, value, computedValue) accettano i formati di input descritti in fondo alla pagina.

Per operazioni ripetute con la stessa configurazione CSS, chiamate una volta tw::compile() e riutilizzate il valore restituito 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

Analizza il contenuto, estrae i candidati per le classi e restituisce l'CSS generato. L'impostazione predefinita $css è @import "tailwindcss"; e include tema, preflight e utility. Restituisce 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,
]);

La forma array accetta queste chiavi:

Chiave	Tipo	Scopo
`content`	`string`	Contenuto da analizzare per individuare i candidati di classe (obbligatorio)
`css`	`string`	Input CSS con direttive Tailwind (predefinito `@import "tailwindcss";`)
`minify`	`bool`	Minimizza l'output (predefinito `false`)
`importPaths`	`string \| array \| callable \| null`	Carica CSS dal file system con risoluzione `@import` completa — vedi Importazione di CSS
`cache`	`bool \| string`	Abilita la cache su file — vedi Cache
`cacheTtl`	`int`	Durata della cache in secondi

tw::compile()

PHP

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

Crea un TailwindCompiler riutilizzabile associato al valore CSS indicato. L'analisi e la costruzione del design system avvengono una sola volta: è la scelta più efficiente quando si genera CSS per molte stringhe di contenuto diverse. Usate generate() per accumulare un foglio di stile tra le chiamate oppure generateExact() per generare output indipendenti per pagina. Restituisce 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">');

L'array $options accetta:

Opzione	Tipo	Scopo
`stateCacheFile`	`string`	Percorso di un file PHP che conserva lo stato di costruzione del compilatore tra richieste e processi — vedi Cache dello stato del compilatore
`polyfills`	`int`	Quali fallback generare, come maschera di bit di `TailwindPHP\POLYFILL_AT_PROPERTY` (i valori predefiniti `@layer properties` per le variabili `@property`) e `TailwindPHP\POLYFILL_COLOR_MIX` (fallback statici per i colori prima di `color-mix()`). Predefinito `POLYFILL_ALL`; `POLYFILL_NONE` li disabilita entrambi
`importSearchPaths`	`array<string>`	Directory da cercare quando si risolve `@import` dal file system

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)

Per l'intera API dei metodi di istanza, vedi Metodi dell'istanza TailwindCompiler.

tw::properties()

PHP

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

Restituisce le proprietà CSS grezze di una classe, lasciando irrisolte le variabili CSS. Restituisce array<string, string> (nome proprietà → valore).

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

Come properties(), ma risolve ogni variabile CSS in un valore concreto. Restituisce 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

Restituisce il valore grezzo di una singola classe utility. Restituisce ?string — null se l'utility non viene trovata.

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

Restituisce il valore risolto di una singola classe utility. Restituisce ?string — null se l'utility non viene trovata.

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

Estrae dal contenuto i nomi di classe Tailwind (legge gli attributi class e className). Restituisce 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

Estrae i candidati per i nomi di classe da ogni stringa tra virgolette singole o doppie nel codice sorgente; è utile per i template che creano elenchi di classi in variabili anziché negli attributi class. Ogni stringa viene suddivisa in base agli spazi e vengono mantenuti tutti i token che sembrano nomi di classe. Restituisce 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);

Anche le parole comuni superano il controllo (hello, world qui sopra); non generano nulla a meno che non siano nomi di utility. Passate il risultato a css(), perché generate() legge solo gli attributi class.

tw::cssMap()

PHP

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

Crea una mappa inversa dalle dichiarazioni CSS alle classi utility, utile per convertire CSS esistenti in classi Tailwind. Le chiavi sono stringhe "property: value" con le variabili risolte (le utility con più proprietà ricevono anche una chiave "prop: value; prop: value"); i valori sono nomi di classe. Restituisce 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'

La mappa copre un elenco fisso di utility comuni (display, position, flexbox, tipografia, valori di spaziatura e dimensionamento, bordi, colori nero/bianco/trasparente e simili), non tutte le utility né tutti i colori del tema. L'argomento $css modifica i valori risolti di queste utility, ma i token personalizzati del tema, come --color-brand, non aggiungono voci.

tw::minify()

PHP

public static function minify(string $css): string

Minimizza una stringa CSS arbitraria: rimuove i commenti, compatta gli spazi, abbrevia i colori esadecimali (#ffffff → #fff), rimuove le unità dai valori zero (0px → 0) e altro ancora. Restituisce string.

Per CSS generato direttamente da TailwindPHP, preferite l'opzione minify (tw::generate(['minify' => true])) o il parametro $minify dei metodi del compilatore. Questo percorso minimizza durante la serializzazione: è più veloce e preserva i selettori discendenti :not() che il passaggio basato su stringhe compatta.

PHP

use TailwindPHP\tw;

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

Per tutte le ottimizzazioni, vedi Cache e minimizzazione.

tw::clearCache()

PHP

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

Elimina i file CSS memorizzati nella cache. Passate true (o omettetelo) per usare la directory predefinita della cache, oppure una stringa di percorso per indicarne una personalizzata. Restituisce int, il numero di file eliminati.

PHP

use TailwindPHP\tw;

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

È disponibile anche una funzione TailwindPHP\clearCache() autonoma.

tw::colors()

PHP

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

Restituisce tutti i valori dei colori del tema. Restituisce array<string, string> (nome del colore → valore calcolato).

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

Restituisce tutti i valori dei breakpoint del tema. Restituisce array<string, string> (nome del breakpoint → valore).

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

Restituisce i valori di spaziatura personalizzati del tema. Restituisce array<string, string> (nome della spaziatura → valore).

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

Formati di input

I metodi di ispezione (generate, properties, computedProperties, value, computedValue) accettano tre forme di input:

Formato	Esempio
Solo stringa	`tw::generate('<div class="flex">')`
Stringa + stringa CSS	`tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')`
Array con `content` (+ `css` facoltativo)	`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";']);

Metodi dell'istanza TailwindCompiler

L'oggetto restituito da tw::compile() espone la stessa API di ispezione della classe statica, associata alla configurazione CSS usata per la compilazione. Usatelo per evitare di analizzare nuovamente il tema a ogni chiamata.

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

Generazione cumulativa e puntuale

generate() e css() sono cumulativi: ogni chiamata aggiunge i propri candidati all'insieme crescente del compilatore e il foglio di stile restituito include tutto ciò che è stato elaborato fino a quel momento. È adatto a un unico foglio di stile costruito attraverso più template.

generateExact() e cssExact() compilano esattamente il contenuto o i candidati indicati a ogni chiamata, senza mantenere dati tra le chiamate, riutilizzando però il design system già analizzato dal compilatore. L'output corrisponde a quello prodotto da una compilazione tw::generate() a freddo dello stesso contenuto. È il modo più rapido per creare CSS per pagina con un unico compilatore di lunga durata:

PHP

use TailwindPHP\tw;

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

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

Tutti e quattro i metodi accettano il flag facoltativo $minify, che genera CSS minimizzato durante la serializzazione: è identico byte per byte a tw::generate(['minify' => true]) e più efficiente della minimizzazione successiva dell'output formattato.

Strumenti di ispezione avanzati

Per esaminare direttamente lo stato compilato:

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

Restituiscono strutture interne; per i relativi contenuti, vedi Architettura.

Funzioni di livello inferiore

La classe tw racchiude un insieme di funzioni con spazio dei nomi in TailwindPHP. Sono utili quando serve il risultato grezzo della compilazione anziché un TailwindCompiler:

Funzione	Scopo
`compile(string $css, array $options = []): array`	Analizza e compila CSS. Restituisce `build` (cumulativo) e le closure `buildExact` che accettano candidati e un flag `$minify` facoltativo, oltre a `sources`, `root`, `features` e `designSystem`. Accetta le stesse opzioni di `tw::compile()`, tranne `stateCacheFile`
`StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array`	`compile()` con la cache dello stato del compilatore persistente
`parseCssState()`, `finalizeCssState()`, `compileParsed()`	Le due fasi dell'analisi (uno stato serializzabile, poi le closure ricostruite a partire da esso) e la fase finale di assemblaggio usata da `compileCssCached()`. `parseCss()` e `compileAst()` restano gli equivalenti in un solo passaggio

PHP

use function TailwindPHP\compile;

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

Memorizzazione nella cache

tw::generate() può memorizzare su disco i file CSS compilati, così input identici non richiedono una nuova compilazione.

Opzione	Tipo	Predefinito	Scopo
`cache`	`bool \| string`	`false`	`true` abilita la directory predefinita; con una stringa di percorso, la cache viene salvata lì
`cacheTtl`	`int`	nessuno	Durata della cache in secondi; le voci scadute vengono ricompilate

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

La chiave della cache deriva dal contenuto, dalla configurazione CSS e dall'opzione minify; input diversi producono quindi file di cache distinti. Svuotate la cache con tw::clearCache() o con la funzione autonoma TailwindPHP\clearCache().

Per una guida più approfondita, vedi Cache e minimizzazione.