API

Ver como Markdown Editar no GitHub Documentação em 3843abd

Toda a interface estática fica em uma classe: TailwindPHP\tw (um alias da classe interna Tailwind). Todos os métodos podem ser chamados estaticamente, e os métodos de inspeção (properties, computedProperties, value, computedValue) aceitam os formatos de entrada descritos no fim desta página.

Para repetir operações com a mesma configuração de CSS, chame tw::compile() uma vez e reutilize o TailwindCompiler retornado.

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

Analisa o conteúdo, extrai candidatos a classes e retorna o CSS gerado. O padrão $css é @import "tailwindcss";, que inclui tema, preflight e utilitários. Retorna 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,
]);

A forma de array aceita estas chaves:

Chave	Tipo	Finalidade
`content`	`string`	Conteúdo a ser analisado em busca de candidatos a classes (obrigatório)
`css`	`string`	Entrada CSS com diretivas Tailwind (padrão `@import "tailwindcss";`)
`minify`	`bool`	Minificar a saída (padrão `false`)
`importPaths`	`string \| array \| callable \| null`	Carregar CSS do sistema de arquivos com resolução completa de `@import` — consulte Importação de CSS
`cache`	`bool \| string`	Ativar o cache de arquivos — consulte Cache
`cacheTtl`	`int`	Duração do cache em segundos

tw::compile()

PHP

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

Cria um TailwindCompiler reutilizável vinculado à CSS informada. A análise e a construção do sistema de design acontecem uma única vez, tornando essa a opção eficiente para gerar CSS para várias strings de conteúdo diferentes. Use generate() para acumular uma folha de estilos em várias chamadas ou generateExact() para gerar saídas independentes por página. Retorna 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">');

O array $options aceita:

Opção	Tipo	Finalidade
`stateCacheFile`	`string`	Caminho de um arquivo PHP que persiste o estado de construção do compilador entre requisições e processos — consulte Cache de estado do compilador
`polyfills`	`int`	Quais alternativas emitir, como máscara de bits de `TailwindPHP\POLYFILL_AT_PROPERTY` (os padrões de `@layer properties` para variáveis `@property`) e `TailwindPHP\POLYFILL_COLOR_MIX` (alternativas de cores estáticas antes de `color-mix()`). Padrão `POLYFILL_ALL`; `POLYFILL_NONE` desativa ambas
`importSearchPaths`	`array<string>`	Diretórios a pesquisar ao resolver `@import` no sistema de arquivos

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)

Consulte Métodos de instância do TailwindCompiler para ver toda a interface de instância.

tw::properties()

PHP

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

Retorna as propriedades CSS brutas de uma classe, mantendo as variáveis CSS sem resolução. Retorna array<string, string> (nome da propriedade → valor).

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

Como properties(), mas com cada variável CSS resolvida para um valor concreto. Retorna 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

Retorna o valor bruto de uma única classe utilitária. Retorna ?string — null se o utilitário não for encontrado.

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

Retorna o valor resolvido de uma única classe utilitária. Retorna ?string — null se o utilitário não for encontrado.

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

Extrai nomes de classes Tailwind do conteúdo (lê os atributos class e className). Retorna 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

Extrai candidatos a nomes de classes de todas as strings entre aspas simples ou duplas no código-fonte. Isso serve para templates que montam listas de classes em variáveis, em vez de atributos class. Cada string é dividida nos espaços em branco e todos os tokens que parecem nomes de classes são mantidos. Retorna 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);

Palavras simples também passam na verificação (hello, world acima); elas não geram nada, a menos que por acaso sejam nomes de utilitários. Passe o resultado para css(), pois generate() lê apenas atributos class.

tw::cssMap()

PHP

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

Cria um mapa reverso de declarações CSS para classes utilitárias, útil para converter CSS existentes em classes Tailwind. As chaves são strings "property: value" com as variáveis resolvidas (utilitários com várias propriedades também recebem uma chave "prop: value; prop: value"); os valores são nomes de classes. Retorna 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'

O mapa abrange uma lista fixa de utilitários comuns (display, posição, flexbox, tipografia, etapas de espaçamento e dimensionamento, bordas, cores preto/branco/transparente e semelhantes), não todos os utilitários ou cores do tema. O argumento $css altera os valores resolvidos desses utilitários, mas tokens personalizados do tema (como --color-brand) não adicionam entradas.

tw::minify()

PHP

public static function minify(string $css): string

Minifica uma string CSS arbitrária: remove comentários, compacta espaços em branco, encurta cores hexadecimais (#ffffff → #fff), remove unidades de valores zero (0px → 0) e muito mais. Retorna string.

Para CSS que TailwindPHP gera por conta própria, prefira a opção minify (tw::generate(['minify' => true])) ou o parâmetro $minify dos métodos do compilador. Esse caminho minifica durante a serialização, o que é mais rápido e preserva seletores descendentes :not() que a etapa baseada em strings elimina.

PHP

use TailwindPHP\tw;

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

Consulte Cache e minificação para ver todas as otimizações.

tw::clearCache()

PHP

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

Exclui arquivos CSS em cache. Passe true (ou omita) para usar o diretório de cache padrão, ou uma string de caminho para um diretório personalizado. Retorna int — o número de arquivos excluídos.

PHP

use TailwindPHP\tw;

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

Também há uma função TailwindPHP\clearCache() independente disponível.

tw::colors()

PHP

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

Retorna todos os valores de cores do tema. Retorna array<string, string> (nome da cor → valor calculado).

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

Retorna todos os valores de pontos de quebra do tema. Retorna array<string, string> (nome do ponto de quebra → valor).

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

Retorna os valores de espaçamento personalizados do tema. Retorna array<string, string> (nome do espaçamento → valor).

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

Formatos de entrada

Os métodos de inspeção (generate, properties, computedProperties, value, computedValue) aceitam três formatos de entrada:

Formato	Exemplo
Apenas string	`tw::generate('<div class="flex">')`
String + string CSS	`tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')`
Array com `content` (+ `css` opcional)	`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étodos de instância do TailwindCompiler

O objeto retornado por tw::compile() expõe a mesma interface de inspeção da classe estática, vinculada à CSS com a qual foi compilado. Use-o para evitar analisar o tema novamente em cada chamada.

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

Geração acumulativa e exata

generate() e css() acumulam: cada chamada adiciona seus candidatos ao conjunto crescente do compilador, e a folha de estilos retornada abrange tudo que foi visto até então. Isso funciona bem para criar uma única folha de estilos a partir de vários templates.

generateExact() e cssExact() compilam exatamente o conteúdo ou os candidatos informados em cada chamada, sem reaproveitar dados de chamadas anteriores, mas ainda reutilizando o sistema de design analisado pelo compilador. A saída corresponde à que uma tw::generate() nova do mesmo conteúdo produziria. Essa é a maneira mais rápida de gerar CSS por página com um compilador de longa duração:

PHP

use TailwindPHP\tw;

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

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

Os quatro métodos aceitam um sinalizador $minify opcional que gera CSS minificado durante a serialização, idêntico byte a byte a tw::generate(['minify' => true]) e mais econômico do que minificar depois a saída formatada.

Inspetores avançados

Para inspecionar diretamente o estado compilado:

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

Eles retornam estruturas internas; consulte Arquitetura para saber o que elas contêm.

Funções de baixo nível

A classe tw reúne um conjunto de funções com namespace em TailwindPHP. Elas são úteis quando você precisa do resultado bruto da compilação, em vez de um TailwindCompiler:

Função	Finalidade
`compile(string $css, array $options = []): array`	Analisa e compila CSS. Retorna `build` (acumulativo) e closures `buildExact` que recebem candidatos e um sinalizador `$minify` opcional, além de `sources`, `root`, `features` e `designSystem`. Aceita as mesmas opções que `tw::compile()`, exceto `stateCacheFile`
`StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array`	`compile()` com o cache de estado do compilador persistente
`parseCssState()`, `finalizeCssState()`, `compileParsed()`	As duas etapas da análise (um estado serializável e, em seguida, as closures recriadas a partir dele) e a etapa final de montagem usada por `compileCssCached()`. `parseCss()` e `compileAst()` continuam sendo os equivalentes de uma única etapa

PHP

use function TailwindPHP\compile;

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

Cache

tw::generate() pode armazenar CSS compilado em disco para que entradas idênticas não precisem ser recompiladas.

Opção	Tipo	Padrão	Finalidade
`cache`	`bool \| string`	`false`	`true` ativa o diretório padrão; uma string de caminho armazena o cache nesse local
`cacheTtl`	`int`	nenhum	Duração do cache em segundos; as entradas expiradas são recompiladas

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

A chave do cache deriva do conteúdo, da configuração de CSS e da opção minify, então entradas diferentes geram arquivos de cache diferentes. Limpe as entradas com tw::clearCache() ou com a função TailwindPHP\clearCache() independente.

Para consultar o guia detalhado, veja Cache e minificação.