# API 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](#input-formats) descritos no fim desta página. Para repetir operações com a mesma configuração de CSS, chame [`tw::compile()`](#twcompile) uma vez e reutilize o [`TailwindCompiler`](#tailwindcompiler-instance-methods) retornado. ```php use TailwindPHP\tw; $css = tw::generate('
'); ``` ## 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('
'); // String with custom CSS $css = tw::generate('
', '@import "tailwindcss"; @theme { --color-brand: #3b82f6; }'); // Array input with options $css = tw::generate([ 'content' => '
', '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](https://tailwindphp.inline0.dev/pt/docs/usage/imports) | | `cache` | `bool \| string` | Ativar o cache de arquivos — consulte [Cache](#caching) | | `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()`](#accumulating-vs-exact-generation) 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('
'); ``` 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](https://tailwindphp.inline0.dev/pt/docs/advanced/caching#compiler-state-cache) | | `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` | 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('
'); // .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](#tailwindcompiler-instance-methods) 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` (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()`](#twproperties), mas com cada variável CSS resolvida para um valor concreto. **Retorna** `array`. ```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`. ```php use TailwindPHP\tw; tw::extractCandidates('
'); // ['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`. ```php use TailwindPHP\tw; $classes = tw::extractCandidatesFromStrings(''); // ['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()`](#tailwindcompiler-instance-methods), 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`. ```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](#tailwindcompiler-instance-methods). 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('
'); $minified = tw::minify($css); ``` Consulte [Cache e minificação](https://tailwindphp.inline0.dev/pt/docs/advanced/caching) 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` (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` (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` (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('
')` | | String + string CSS | `tw::generate('
', '@import "tailwindcss"; @theme { ... }')` | | Array com `content` (+ `css` opcional) | `tw::generate(['content' => '
', '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()`](#twcompile) 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('
'); $candidates = $compiler->extractCandidates('
'); $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](https://tailwindphp.inline0.dev/pt/docs/advanced/architecture) 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()`](#twcompile), exceto `stateCacheFile` | | `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | `compile()` com o [cache de estado do compilador](https://tailwindphp.inline0.dev/pt/docs/advanced/caching#compiler-state-cache) 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' => '
', 'cache' => true, ]); // Custom directory + TTL $css = tw::generate([ 'content' => '
', '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()`](#twclearcache) ou com a função `TailwindPHP\clearCache()` independente. Para consultar o guia detalhado, veja [Cache e minificação](https://tailwindphp.inline0.dev/pt/docs/advanced/caching).