# API

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](#input-formats) descritti in fondo alla pagina.

Per operazioni ripetute con la stessa configurazione CSS, chiamate una volta [`tw::compile()`](#twcompile) e riutilizzate il valore restituito [`TailwindCompiler`](#tailwindcompiler-instance-methods).

```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](https://tailwindphp.inline0.dev/it/docs/usage/imports) |
| `cache` | `bool \| string` | Abilita la cache su file — vedi [Cache](#caching) |
| `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()`](#accumulating-vs-exact-generation) 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](https://tailwindphp.inline0.dev/it/docs/advanced/caching#compiler-state-cache) |
| `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](#tailwindcompiler-instance-methods).

## 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()`](#twproperties), 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()`](#tailwindcompiler-instance-methods), 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](#tailwindcompiler-instance-methods). 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](https://tailwindphp.inline0.dev/it/docs/advanced/caching).

## 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()`](#twcompile) 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](https://tailwindphp.inline0.dev/it/docs/advanced/architecture).

### 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()`](#twcompile), tranne `stateCacheFile` |
| `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | `compile()` con la [cache dello stato del compilatore](https://tailwindphp.inline0.dev/it/docs/advanced/caching#compiler-state-cache) 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()`](#twclearcache) o con la funzione autonoma `TailwindPHP\clearCache()`.

Per una guida più approfondita, vedi [Cache e minimizzazione](https://tailwindphp.inline0.dev/it/docs/advanced/caching).