# API

Die gesamte statische Oberfläche liegt in einer Klasse: `TailwindPHP\tw` (ein Alias der internen Klasse `Tailwind`). Alle Methoden lassen sich statisch aufrufen. Die Inspektionsmethoden (`properties`, `computedProperties`, `value`, `computedValue`) akzeptieren die [Eingabeformate](#input-formats), die am Ende dieser Seite beschrieben sind.

Wenn du wiederholt mit derselben Konfiguration von CSS arbeitest, rufe [`tw::compile()`](#twcompile) einmal auf und verwende die zurückgegebene [`TailwindCompiler`](#tailwindcompiler-instance-methods) erneut.

```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
```

Parst Inhalte, extrahiert Klassenkandidaten und gibt das generierte CSS zurück. Der Standardwert für `$css` ist `@import "tailwindcss";` und lädt Theme, Preflight und Utilities. **Rückgabe** `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,
]);
```

Für die Array-Form werden folgende Schlüssel unterstützt:

| Schlüssel | Typ | Zweck |
|---|---|---|
| `content` | `string` | Zu durchsuchende Inhalte für Klassenkandidaten (erforderlich) |
| `css` | `string` | Eingabe-CSS mit Tailwind-Direktiven (Standard: `@import "tailwindcss";`) |
| `minify` | `bool` | Ausgabe minimieren (Standard: `false`) |
| `importPaths` | `string \| array \| callable \| null` | CSS aus dem Dateisystem mit vollständiger `@import`-Auflösung laden — siehe [Imports CSS](https://tailwindphp.inline0.dev/de/docs/usage/imports) |
| `cache` | `bool \| string` | Datei-Caching aktivieren — siehe [Caching](#caching) |
| `cacheTtl` | `int` | Cache-Lebensdauer in Sekunden |

## tw::compile()

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

Erstellt einen wiederverwendbaren `TailwindCompiler`, der an die angegebene CSS gebunden ist. Parsing und Aufbau des Design-Systems erfolgen einmalig. Daher eignet sich diese Variante, wenn CSS für viele verschiedene Inhaltszeichenfolgen erzeugt werden. Verwende `generate()`, um ein Stylesheet über mehrere Aufrufe hinweg aufzubauen, oder [`generateExact()`](#accumulating-vs-exact-generation) für eine separate Ausgabe pro Seite. **Rückgabewert** `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">');
```

Das Array `$options` akzeptiert folgende Einträge:

| Option | Typ | Zweck |
|---|---|---|
| `stateCacheFile` | `string` | Pfad zu einer PHP-Datei, in der der Konstruktionszustand des Compilers über Anfragen und Prozesse hinweg gespeichert wird — siehe [Compilerzustand-Cache](https://tailwindphp.inline0.dev/de/docs/advanced/caching#compiler-state-cache) |
| `polyfills` | `int` | Legt fest, welche Fallbacks ausgegeben werden: eine Bitmaske aus `TailwindPHP\POLYFILL_AT_PROPERTY` (die `@layer properties`-Standards für `@property`-Variablen) und `TailwindPHP\POLYFILL_COLOR_MIX` (statische Farb-Fallbacks vor `color-mix()`). Standard: `POLYFILL_ALL`; `POLYFILL_NONE` deaktiviert beide |
| `importSearchPaths` | `array<string>` | Zu durchsuchende Verzeichnisse, wenn `@import` im Dateisystem aufgelöst wird |

```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)
```

Eine vollständige Übersicht aller Instanzmethoden findest du unter [TailwindCompiler-Instanzmethoden](#tailwindcompiler-instance-methods).

## tw::properties()

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

Gibt die **rohen** CSS-Eigenschaften einer Klasse zurück, wobei CSS-Variablen nicht aufgelöst werden. **Rückgabewert** `array<string, string>` (Eigenschaftsname → Wert).

```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
```

Wie [`properties()`](#twproperties), aber mit allen CSS-Variablen, die zu konkreten Werten aufgelöst sind. **Rückgabewert** `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
```

Gibt den **rohen** Wert einer einzelnen Utility-Klasse zurück. **Rückgabewert** `?string` — `null`, wenn die Utility nicht gefunden wird.

```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
```

Gibt den **aufgelösten** Wert einer einzelnen Utility-Klasse zurück. **Rückgabewert** `?string` — `null`, wenn die Utility nicht gefunden wird.

```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
```

Extrahiert Tailwind-Klassennamen aus Inhalten (liest sowohl `class`- als auch `className`-Attribute). **Rückgabewert** `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
```

Extrahiert Klassenkandidaten aus allen Zeichenfolgen im Quellcode, die in einfache oder doppelte Anführungszeichen gesetzt sind. Das eignet sich für Templates, die Klassenlisten in Variablen statt in `class`-Attributen bilden. Jede Zeichenfolge wird an Leerzeichen getrennt; alle Tokens, die wie Klassennamen aussehen, bleiben erhalten. **Rückgabewert** `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);
```

Auch einfache Wörter bestehen die Prüfung (oben `hello`, `world`); sie werden zu nichts kompiliert, sofern es sich nicht um Utility-Namen handelt. Übergib das Ergebnis an [`css()`](#tailwindcompiler-instance-methods), da `generate()` nur `class`-Attribute ausliest.

## tw::cssMap()

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

Erstellt eine umgekehrte Zuordnung von CSS-Deklarationen zu Utility-Klassen, um vorhandenes CSS in Tailwind-Klassen umzuwandeln. Schlüssel sind `"property: value"`-Zeichenfolgen mit aufgelösten Variablen (Utilities mit mehreren Eigenschaften erhalten zusätzlich einen `"prop: value; prop: value"`-Schlüssel); Werte sind Klassennamen. **Rückgabewert** `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'
```

Die Zuordnung umfasst eine feste Liste gängiger Utilities (Display, Position, Flexbox, Typografie, Abstände und Größenstufen, Rahmen, Schwarz, Weiß, transparente Farben und Ähnliches), aber nicht jede Utility und nicht alle Theme-Farben. Das Argument `$css` verändert die aufgelösten Werte dieser Utilities, fügt jedoch keine Einträge für benutzerdefinierte Theme-Tokens wie `--color-brand` hinzu.

## tw::minify()

```php
public static function minify(string $css): string
```

Minimiert eine beliebige CSS-Zeichenfolge: entfernt Kommentare, fasst Leerraum zusammen, kürzt Hex-Farben (`#ffffff` → `#fff`), entfernt Einheiten bei Nullwerten (`0px` → `0`) und mehr. **Rückgabewert** `string`.

Für CSS, die TailwindPHP selbst erzeugt, verwende vorzugsweise die Option `minify` (`tw::generate(['minify' => true])`) oder den Parameter `$minify` der [Compiler-Methoden](#tailwindcompiler-instance-methods). Dabei wird während der Serialisierung minimiert. Das ist schneller und erhält untergeordnete `:not()`-Selektoren, die beim zeichenfolgenbasierten Durchlauf zusammengefasst werden.

```php
use TailwindPHP\tw;

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

Eine vollständige Übersicht der Optimierungen findest du unter [Caching und Minifizierung](https://tailwindphp.inline0.dev/de/docs/advanced/caching).

## tw::clearCache()

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

Löscht zwischengespeicherte CSS-Dateien. Übergib `true` (oder lass es weg), um das Standard-Cache-Verzeichnis zu verwenden, oder einen Pfad als Zeichenfolge für ein benutzerdefiniertes Verzeichnis. **Rückgabewert** `int` — die Anzahl der gelöschten Dateien.

```php
use TailwindPHP\tw;

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

Eine eigenständige Funktion `TailwindPHP\clearCache()` ist ebenfalls verfügbar.

## tw::colors()

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

Gibt alle Farbwerte des Themes zurück. **Rückgabewert** `array<string, string>` (Farbname → berechneter Wert).

```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
```

Gibt alle Breakpoint-Werte des Themes zurück. **Rückgabewert** `array<string, string>` (Breakpoint-Name → Wert).

```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
```

Gibt benutzerdefinierte Abstände aus dem Theme zurück. **Rückgabewert** `array<string, string>` (Abstandsname → Wert).

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

## Eingabeformate

Die Inspektionsmethoden (`generate`, `properties`, `computedProperties`, `value`, `computedValue`) akzeptieren drei Eingabeformen:

| Format | Beispiel |
|---|---|
| Nur Zeichenfolge | `tw::generate('<div class="flex">')` |
| Zeichenfolge + CSS-Zeichenfolge | `tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')` |
| Array mit `content` (+ optionalem `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";']);
```

## TailwindCompiler-Instanzmethoden

Das von [`tw::compile()`](#twcompile) zurückgegebene Objekt stellt dieselben Inspektionsmethoden wie die statische Klasse bereit, gebunden an die CSS, mit der es kompiliert wurde. So musst du das Theme nicht bei jedem Aufruf erneut einlesen.

```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
```

### Kumulierte und exakte Generierung

`generate()` und `css()` **kumulieren**: Jeder Aufruf fügt seine Kandidaten zur wachsenden Menge des Compilers hinzu; das zurückgegebene Stylesheet umfasst alles, was bisher erfasst wurde. Das eignet sich für ein Stylesheet, das über mehrere Templates hinweg aufgebaut wird.

`generateExact()` und `cssExact()` kompilieren bei jedem Aufruf **genau** die angegebenen Inhalte oder Kandidaten, ohne sie aus vorherigen Aufrufen zu übernehmen. Das bereits eingelesene Design-System des Compilers wird weiterverwendet. Die Ausgabe entspricht der eines neuen `tw::generate()` mit denselben Inhalten. So erzeugst du am schnellsten seitenbezogenes CSS mit einem langlebigen Compiler:

```php
use TailwindPHP\tw;

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

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

Alle vier Methoden akzeptieren ein optionales Flag `$minify`, das CSS während der Serialisierung minimiert ausgibt. Die Ausgabe ist byteidentisch mit `tw::generate(['minify' => true])` und günstiger, als die lesbar formatierte Ausgabe nachträglich zu minimieren.

### Erweiterte Inspektoren

Um den kompilierten Zustand direkt zu untersuchen:

```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
```

Diese Methoden geben interne Strukturen zurück. Was darin enthalten ist, erfährst du unter [Architektur](https://tailwindphp.inline0.dev/de/docs/advanced/architecture).

### Funktionen auf niedrigerer Ebene

Die Klasse `tw` kapselt eine Reihe von Funktionen im Namensraum `TailwindPHP`. Sie sind hilfreich, wenn du statt eines `TailwindCompiler` das rohe Kompilierungsergebnis brauchst:

| Funktion | Zweck |
|---|---|
| `compile(string $css, array $options = []): array` | Liest CSS ein und kompiliert es. Gibt `build` (kumuliert) und `buildExact`-Closures zurück, die Kandidaten und ein optionales Flag `$minify` entgegennehmen, außerdem `sources`, `root`, `features` und `designSystem`. Akzeptiert dieselben Optionen wie [`tw::compile()`](#twcompile), außer `stateCacheFile` |
| `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | `compile()` mit dem persistenten [Compilerzustand-Cache](https://tailwindphp.inline0.dev/de/docs/advanced/caching#compiler-state-cache) |
| `parseCssState()`, `finalizeCssState()`, `compileParsed()` | Die zwei Schritte des Parsings (zuerst ein serialisierbarer Zustand, dann die daraus neu aufgebauten Closures) und der abschließende Zusammenbau, den `compileCssCached()` verwendet. `parseCss()` und `compileAst()` bieten weiterhin die entsprechenden Funktionen in einem Schritt |

```php
use function TailwindPHP\compile;

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

## Caching

`tw::generate()` kann kompilierte CSS auf dem Datenträger zwischenspeichern, sodass identische Eingaben nicht erneut kompiliert werden müssen.

| Option | Typ | Standardwert | Zweck |
|---|---|---|---|
| `cache` | `bool \| string` | `false` | `true` aktiviert das Standardverzeichnis; bei einem Pfad als Zeichenfolge wird dort zwischengespeichert |
| `cacheTtl` | `int` | keiner | Cache-Lebensdauer in Sekunden; abgelaufene Einträge werden neu kompiliert |

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

Der Cache-Schlüssel wird aus dem **Inhalt**, der **CSS-Konfiguration** und der Option **minify** abgeleitet. Verschiedene Eingaben erzeugen daher verschiedene Cache-Dateien. Lösche Einträge mit [`tw::clearCache()`](#twclearcache) oder der eigenständigen Funktion `TailwindPHP\clearCache()`.

Die ausführliche Anleitung findest du unter [Caching und Minifizierung](https://tailwindphp.inline0.dev/de/docs/advanced/caching).