API

Afficher au format Markdown Modifier sur GitHub Documentation de 3843abd

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 décrits au bas de cette page.

Pour les opérations répétées avec la même configuration CSS, appelez tw::compile() une seule fois, puis réutilisez l'objet TailwindCompiler 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
`cache`	`bool \| string`	Activer le cache de fichiers — voir Mise en cache
`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() 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
`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 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(), 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(), 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. 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 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() 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 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()`, sauf `stateCacheFile`
`StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array`	`compile()` avec le cache d'état du compilateur 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() ou la fonction autonome TailwindPHP\clearCache().

Pour le guide détaillé, consultez Mise en cache et minification.