# API

Toute la surface statique se trouve dans une seule classe : `TailwindPHP\tw` (un alias de la classe interne `Tailwind`). Chaque méthode est appelable de façon statique, et les méthodes d'inspection (`properties`, `computedProperties`, `value`, `computedValue`) acceptent toutes les [formats d'entrée](#input-formats) décrits au bas de cette page.

Pour les opérations répétées avec la même configuration CSS, appelez [`tw::compile()`](#twcompile) une seule fois, puis réutilisez l'objet [`TailwindCompiler`](#tailwindcompiler-instance-methods) renvoyé.

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

Analyse le contenu, extrait les classes candidates et renvoie le CSS généré. Par défaut, `$css` vaut `@import "tailwindcss";`, ce qui inclut le thème, le préflight et les utilitaires. **Renvoie** `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 forme tableau accepte les clés suivantes :

| Clé | Type | Rôle |
|---|---|---|
| `content` | `string` | Contenu à analyser pour trouver les classes candidates (obligatoire) |
| `css` | `string` | CSS d'entrée avec les directives Tailwind (par défaut `@import "tailwindcss";`) |
| `minify` | `bool` | Minifier la sortie (par défaut `false`) |
| `importPaths` | `string \| array \| callable \| null` | Charger CSS depuis le système de fichiers avec la résolution complète de `@import` — voir [Importer CSS](https://tailwindphp.inline0.dev/fr/docs/usage/imports) |
| `cache` | `bool \| string` | Activer le cache de fichiers — voir [Mise en cache](#caching) |
| `cacheTtl` | `int` | Durée de conservation du cache en secondes |

## tw::compile()

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

Crée un `TailwindCompiler` réutilisable lié au CSS indiqué. L'analyse et la construction du système de conception n'ont lieu qu'une fois ; c'est donc le choix efficace pour générer du CSS à partir de nombreux contenus différents. Utilisez `generate()` pour accumuler une feuille de style au fil des appels, ou [`generateExact()`](#accumulating-vs-exact-generation) pour produire une sortie indépendante par page. **Renvoie** `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">');
```

Le tableau `$options` accepte :

| Option | Type | Rôle |
|---|---|---|
| `stateCacheFile` | `string` | Chemin d'un fichier PHP qui conserve l'état de construction du compilateur entre les requêtes et les processus — voir [Cache d'état du compilateur](https://tailwindphp.inline0.dev/fr/docs/advanced/caching#compiler-state-cache) |
| `polyfills` | `int` | Solutions de repli à émettre, sous forme de masque de bits composé de `TailwindPHP\POLYFILL_AT_PROPERTY` (les valeurs par défaut de `@layer properties` pour les variables `@property`) et de `TailwindPHP\POLYFILL_COLOR_MIX` (solutions de repli de couleur statiques avant `color-mix()`). Valeur par défaut : `POLYFILL_ALL` ; `POLYFILL_NONE` désactive les deux |
| `importSearchPaths` | `array<string>` | Répertoires à parcourir pour résoudre `@import` depuis le système de fichiers |

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

Consultez [Méthodes d'instance de TailwindCompiler](#tailwindcompiler-instance-methods) pour découvrir toutes les méthodes d'instance.

## tw::properties()

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

Renvoie les propriétés CSS **brutes** d'une classe, en laissant les variables CSS non résolues. **Renvoie** `array<string, string>` (propriété → valeur).

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

Comme [`properties()`](#twproperties), mais avec toutes les variables CSS résolues en valeurs concrètes. **Renvoie** `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
```

Renvoie la valeur **brute** d'une seule classe utilitaire. **Renvoie** `?string` — `null` si l'utilitaire est introuvable.

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

Renvoie la valeur **résolue** d'une seule classe utilitaire. **Renvoie** `?string` — `null` si l'utilitaire est introuvable.

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

Extrait les noms de classes Tailwind du contenu (lit les attributs `class` et `className`). **Renvoie** `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
```

Extrait les noms de classes candidates de chaque chaîne entre guillemets simples ou doubles dans le code source. Cette méthode convient aux modèles qui construisent des listes de classes dans des variables plutôt que dans des attributs `class`. Chaque chaîne est découpée aux espaces, et chaque élément ressemblant à un nom de classe est conservé. **Renvoie** `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);
```

Les mots ordinaires passent aussi la vérification (`hello`, `world` ci-dessus) ; ils ne produisent rien à la compilation, sauf s'ils correspondent à des noms d'utilitaires. Transmettez le résultat à [`css()`](#tailwindcompiler-instance-methods), car `generate()` ne lit que les attributs `class`.

## tw::cssMap()

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

Crée une table de correspondance inverse entre les déclarations CSS et les classes utilitaires, pratique pour convertir du CSS existant en classes Tailwind. Les clés sont des chaînes `"property: value"` dont les variables sont résolues (les utilitaires à plusieurs propriétés ont aussi une clé `"prop: value; prop: value"`), et les valeurs sont des noms de classes. **Renvoie** `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 table couvre une liste fixe d'utilitaires courants (affichage, position, flexbox, typographie, espacements et tailles prédéfinis, bordures, couleurs noir, blanc et transparent, etc.), mais pas tous les utilitaires ni toutes les couleurs du thème. L'argument `$css` modifie les valeurs résolues de ces utilitaires, mais les jetons de thème personnalisés (tels que `--color-brand`) n'ajoutent aucune entrée.

## tw::minify()

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

Minifie une chaîne CSS quelconque : supprime les commentaires, réduit les espaces, raccourcit les couleurs hexadécimales (`#ffffff` → `#fff`), supprime les unités des valeurs nulles (`0px` → `0`), et plus encore. **Renvoie** `string`.

Pour le CSS que TailwindPHP génère elle-même, préférez l'option `minify` (`tw::generate(['minify' => true])`) ou le paramètre `$minify` des [méthodes du compilateur](#tailwindcompiler-instance-methods). Cette méthode minifie lors de la sérialisation ; elle est donc plus rapide et préserve les sélecteurs `:not()` descendants que le traitement des chaînes réduit.

```php
use TailwindPHP\tw;

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

Consultez [Mise en cache et minification](https://tailwindphp.inline0.dev/fr/docs/advanced/caching) pour découvrir toutes les optimisations.

## tw::clearCache()

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

Supprime les fichiers CSS mis en cache. Passez `true` (ou omettez-le) pour utiliser le répertoire de cache par défaut, ou une chaîne de chemin pour indiquer un répertoire personnalisé. **Renvoie** `int` — le nombre de fichiers supprimés.

```php
use TailwindPHP\tw;

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

Une fonction autonome `TailwindPHP\clearCache()` est également disponible.

## tw::colors()

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

Renvoie toutes les valeurs de couleur du thème. **Renvoie** `array<string, string>` (nom de couleur → valeur calculée).

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

Renvoie toutes les valeurs des points de rupture du thème. **Renvoie** `array<string, string>` (nom du point de rupture → valeur).

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

Renvoie les valeurs d'espacement personnalisées du thème. **Renvoie** `array<string, string>` (nom de l'espacement → valeur).

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

## Formats d'entrée

Les méthodes d'inspection (`generate`, `properties`, `computedProperties`, `value`, `computedValue`) acceptent trois formes d'entrée :

| Format | Exemple |
|---|---|
| Chaîne seule | `tw::generate('<div class="flex">')` |
| Chaîne + chaîne CSS | `tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')` |
| Tableau avec `content` (+ `css` facultatif) | `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";']);
```

## Méthodes d'instance de TailwindCompiler

L'objet renvoyé par [`tw::compile()`](#twcompile) propose les mêmes méthodes d'inspection que la classe statique, liées au CSS avec lequel il a été compilé. Utilisez-le pour éviter d'analyser à nouveau le thème à chaque appel.

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

### Génération cumulative ou exacte

`generate()` et `css()` sont **cumulatives** : chaque appel ajoute ses candidats à l'ensemble croissant du compilateur, et la feuille de style renvoyée couvre tout ce qui a été traité jusque-là. Cette approche convient à une feuille de style construite progressivement à partir de plusieurs modèles.

`generateExact()` et `cssExact()` compilent **exactement** le contenu ou les candidats indiqués à chaque appel, sans report d'un appel à l'autre, tout en réutilisant le système de conception déjà analysé par le compilateur. La sortie correspond à celle d'une `tw::generate()` à froid du même contenu. C'est le moyen le plus rapide de générer le CSS de chaque page avec un compilateur de longue durée :

```php
use TailwindPHP\tw;

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

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

Les quatre méthodes acceptent un indicateur facultatif `$minify` qui produit du CSS minifié lors de la sérialisation, identique octet par octet à `tw::generate(['minify' => true])` et plus économique que de minifier ensuite la sortie mise en forme.

### Inspecteurs avancés

Pour examiner directement l'état compilé :

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

Ces méthodes renvoient des structures internes ; consultez [Architecture](https://tailwindphp.inline0.dev/fr/docs/advanced/architecture) pour connaître leur contenu.

### Fonctions de bas niveau

La classe `tw` enveloppe un ensemble de fonctions avec espace de noms dans `TailwindPHP`. Elles sont utiles lorsque vous avez besoin du résultat brut de la compilation plutôt que d'un `TailwindCompiler` :

| Fonction | Rôle |
|---|---|
| `compile(string $css, array $options = []): array` | Analyse et compile CSS. Renvoie `build` (cumulatif) et `buildExact`, des fonctions de fermeture qui acceptent des candidats et un indicateur `$minify` facultatif, ainsi que `sources`, `root`, `features` et `designSystem`. Accepte les mêmes options que [`tw::compile()`](#twcompile), sauf `stateCacheFile` |
| `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | `compile()` avec le [cache d'état du compilateur](https://tailwindphp.inline0.dev/fr/docs/advanced/caching#compiler-state-cache) persistant |
| `parseCssState()`, `finalizeCssState()`, `compileParsed()` | Les deux étapes de l'analyse (un état sérialisable, puis les fonctions de fermeture reconstruites à partir de celui-ci) et l'étape finale d'assemblage utilisée par `compileCssCached()`. `parseCss()` et `compileAst()` restent les équivalents en une seule étape |

```php
use function TailwindPHP\compile;

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

## Mise en cache

`tw::generate()` peut mettre en cache sur disque les CSS compilés pour éviter de recompiler les entrées identiques.

| Option | Type | Valeur par défaut | Rôle |
|---|---|---|---|
| `cache` | `bool \| string` | `false` | `true` active le répertoire par défaut ; une chaîne de chemin indique où mettre en cache |
| `cacheTtl` | `int` | aucune | Durée de conservation du cache en secondes ; les entrées expirées sont recompilées |

```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 clé de cache est calculée à partir du **contenu**, de la **configuration CSS** et de l'option de minification ; les entrées différentes produisent donc des fichiers de cache différents. Supprimez des entrées avec [`tw::clearCache()`](#twclearcache) ou la fonction autonome `TailwindPHP\clearCache()`.

Pour le guide détaillé, consultez [Mise en cache et minification](https://tailwindphp.inline0.dev/fr/docs/advanced/caching).