# API

Seluruh antarmuka statis tersedia pada satu kelas: `TailwindPHP\tw` (alias untuk kelas internal `Tailwind`). Setiap metode dapat dipanggil secara statis, dan metode inspeksi (`properties`, `computedProperties`, `value`, `computedValue`) menerima [format input](#input-formats) yang dijelaskan di bagian bawah halaman ini.

Untuk pekerjaan berulang dengan konfigurasi CSS yang sama, panggil [`tw::compile()`](#twcompile) sekali dan gunakan kembali [`TailwindCompiler`](#tailwindcompiler-instance-methods) yang dikembalikan.

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

Mengurai konten, mengekstrak kandidat kelas, dan mengembalikan CSS yang dihasilkan. Nilai default `$css` adalah `@import "tailwindcss";`, yang menyertakan tema, preflight, dan utilitas. **Mengembalikan** `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,
]);
```

Bentuk array menerima kunci berikut:

| Kunci | Tipe | Tujuan |
|---|---|---|
| `content` | `string` | Konten yang dipindai untuk mencari kandidat kelas (wajib) |
| `css` | `string` | Input CSS dengan direktif Tailwind (default `@import "tailwindcss";`) |
| `minify` | `bool` | Meminifikasi keluaran (default `false`) |
| `importPaths` | `string \| array \| callable \| null` | Memuat CSS dari sistem file dengan resolusi `@import` penuh — lihat [Mengimpor CSS](https://tailwindphp.inline0.dev/id/docs/usage/imports) |
| `cache` | `bool \| string` | Mengaktifkan caching file — lihat [Caching](#caching) |
| `cacheTtl` | `int` | Masa berlaku cache dalam detik |

## tw::compile()

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

Membuat `TailwindCompiler` yang dapat digunakan kembali dan terikat pada CSS yang diberikan. Penguraian dan pembuatan design system dilakukan sekali, sehingga ini pilihan efisien saat membuat CSS untuk banyak string konten berbeda. Gunakan `generate()` untuk mengumpulkan satu stylesheet dalam beberapa pemanggilan, atau [`generateExact()`](#accumulating-vs-exact-generation) untuk keluaran tiap halaman secara terpisah. **Mengembalikan** `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">');
```

Array `$options` menerima:

| Opsi | Tipe | Tujuan |
|---|---|---|
| `stateCacheFile` | `string` | Jalur file PHP yang menyimpan status pembuatan compiler di antara permintaan dan proses — lihat [Cache status compiler](https://tailwindphp.inline0.dev/id/docs/advanced/caching#compiler-state-cache) |
| `polyfills` | `int` | Fallback yang akan dikeluarkan, sebagai bitmask `TailwindPHP\POLYFILL_AT_PROPERTY` (nilai default `@layer properties` untuk variabel `@property`) dan `TailwindPHP\POLYFILL_COLOR_MIX` (fallback warna statis sebelum `color-mix()`). Default `POLYFILL_ALL`; `POLYFILL_NONE` menonaktifkan keduanya |
| `importSearchPaths` | `array<string>` | Direktori yang dicari saat menyelesaikan `@import` dari sistem file |

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

Lihat [Metode instance TailwindCompiler](#tailwindcompiler-instance-methods) untuk seluruh antarmuka instance.

## tw::properties()

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

Mengembalikan properti CSS **mentah** untuk suatu kelas, dengan variabel CSS yang belum diselesaikan. **Mengembalikan** `array<string, string>` (nama properti → nilai).

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

Seperti [`properties()`](#twproperties), tetapi setiap variabel CSS diselesaikan menjadi nilai konkret. **Mengembalikan** `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
```

Mengembalikan nilai **mentah** untuk satu kelas utilitas. **Mengembalikan** `?string` — `null` jika utilitas tidak ditemukan.

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

Mengembalikan nilai **yang telah diselesaikan** untuk satu kelas utilitas. **Mengembalikan** `?string` — `null` jika utilitas tidak ditemukan.

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

Mengekstrak nama kelas Tailwind dari konten (membaca atribut `class` dan `className`). **Mengembalikan** `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
```

Mengekstrak kandidat nama kelas dari setiap string yang diapit tanda petik tunggal atau ganda dalam kode sumber, untuk templat yang menyusun daftar kelas dalam variabel alih-alih atribut `class`. Setiap string dipisahkan berdasarkan spasi, lalu setiap token yang tampak seperti nama kelas dipertahankan. **Mengembalikan** `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);
```

Kata biasa juga lolos pemeriksaan (`hello`, `world` di atas); kata tersebut tidak menghasilkan apa pun saat dikompilasi, kecuali jika kebetulan merupakan nama utilitas. Teruskan hasilnya ke [`css()`](#tailwindcompiler-instance-methods), karena `generate()` hanya membaca atribut `class`.

## tw::cssMap()

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

Membangun peta balik dari deklarasi CSS ke kelas utilitas, berguna untuk mengonversi CSS yang ada menjadi kelas Tailwind. Kuncinya berupa string `"property: value"` dengan variabel yang sudah diselesaikan (utilitas dengan beberapa properti juga mendapat kunci `"prop: value; prop: value"`), sedangkan nilainya berupa nama kelas. **Mengembalikan** `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'
```

Peta ini mencakup daftar tetap utilitas umum (display, position, flexbox, tipografi, tahapan spacing dan sizing, border, warna hitam/putih/transparan, dan sejenisnya), bukan setiap utilitas atau warna tema. Argumen `$css` mengubah nilai yang telah diselesaikan dari utilitas tersebut, tetapi token tema kustom (seperti `--color-brand`) tidak menambahkan entri.

## tw::minify()

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

Meminifikasi string CSS sembarang: menghapus komentar, merapatkan spasi, mempersingkat warna hex (`#ffffff` → `#fff`), menghapus unit dari nilai nol (`0px` → `0`), dan lainnya. **Mengembalikan** `string`.

Untuk CSS yang dihasilkan sendiri oleh TailwindPHP, gunakan opsi `minify` (`tw::generate(['minify' => true])`) atau parameter `$minify` pada [metode compiler](#tailwindcompiler-instance-methods). Cara ini meminifikasi saat serialisasi, sehingga lebih cepat dan mempertahankan selector `:not()` turunan yang dirapatkan oleh pemrosesan berbasis string.

```php
use TailwindPHP\tw;

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

Lihat [Caching & minifikasi](https://tailwindphp.inline0.dev/id/docs/advanced/caching) untuk rangkaian optimasi lengkap.

## tw::clearCache()

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

Menghapus file CSS yang tersimpan dalam cache. Berikan `true` (atau kosongkan) untuk direktori cache default, atau string jalur untuk direktori khusus. **Mengembalikan** `int` — jumlah file yang dihapus.

```php
use TailwindPHP\tw;

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

Fungsi `TailwindPHP\clearCache()` mandiri juga tersedia.

## tw::colors()

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

Mengembalikan setiap nilai warna dari tema. **Mengembalikan** `array<string, string>` (nama warna → nilai terhitung).

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

Mengembalikan setiap nilai breakpoint dari tema. **Mengembalikan** `array<string, string>` (nama breakpoint → nilai).

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

Mengembalikan nilai spacing kustom dari tema. **Mengembalikan** `array<string, string>` (nama spacing → nilai).

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

## Format input

Metode inspeksi (`generate`, `properties`, `computedProperties`, `value`, `computedValue`) menerima tiga bentuk input:

| Format | Contoh |
|---|---|
| Hanya string | `tw::generate('<div class="flex">')` |
| String + string CSS | `tw::generate('<div class="flex">', '@import "tailwindcss"; @theme { ... }')` |
| Array dengan `content` (+ `css` opsional) | `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";']);
```

## Metode instance TailwindCompiler

Objek yang dikembalikan oleh [`tw::compile()`](#twcompile) menyediakan antarmuka inspeksi yang sama dengan kelas statis, terikat pada CSS yang digunakan saat objek itu dikompilasi. Gunakan untuk menghindari penguraian ulang tema pada setiap pemanggilan.

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

### Pembuatan kumulatif vs. tepat

`generate()` dan `css()` **bersifat kumulatif**: setiap pemanggilan menambahkan kandidat ke kumpulan compiler yang terus bertambah, dan stylesheet yang dikembalikan mencakup semua yang telah ditemukan. Cocok untuk satu stylesheet yang dibangun dari berbagai templat.

`generateExact()` dan `cssExact()` mengompilasi konten atau kandidat yang diberikan secara **tepat** pada setiap pemanggilan, tanpa membawa data dari pemanggilan sebelumnya, sambil tetap menggunakan kembali design system yang telah diurai oleh compiler. Keluarannya sama dengan hasil `tw::generate()` dingin atas konten yang sama. Ini cara tercepat untuk membuat CSS per halaman dari satu compiler yang berjalan lama:

```php
use TailwindPHP\tw;

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

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

Keempat metode menerima flag `$minify` opsional yang menghasilkan CSS termininifikasi saat serialisasi, identik byte demi byte dengan `tw::generate(['minify' => true])` dan lebih hemat daripada meminifikasi keluaran yang diformat setelahnya.

### Pemeriksa lanjutan

Untuk memeriksa status kompilasi secara langsung:

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

Ini mengembalikan struktur internal; lihat [Arsitektur](https://tailwindphp.inline0.dev/id/docs/advanced/architecture) untuk mengetahui isinya.

### Fungsi tingkat rendah

Kelas `tw` membungkus sekumpulan fungsi ber-namespace di `TailwindPHP`. Fungsi ini berguna saat Anda membutuhkan hasil kompilasi mentah, bukan `TailwindCompiler`:

| Fungsi | Tujuan |
|---|---|
| `compile(string $css, array $options = []): array` | Mengurai dan mengompilasi CSS. Mengembalikan penutup `build` (kumulatif) dan `buildExact` yang menerima kandidat serta flag `$minify` opsional, juga `sources`, `root`, `features`, dan `designSystem`. Menerima opsi yang sama seperti [`tw::compile()`](#twcompile) kecuali `stateCacheFile` |
| `StateCache\compileCssCached(string $css, string $cacheFile, array $options = []): array` | `compile()` dengan [cache status compiler](https://tailwindphp.inline0.dev/id/docs/advanced/caching#compiler-state-cache) yang persisten |
| `parseCssState()`, `finalizeCssState()`, `compileParsed()` | Dua tahap penguraian (status yang dapat diserialisasi, lalu penutup yang dibangun kembali darinya) dan langkah perakitan akhir yang digunakan `compileCssCached()`. `parseCss()` dan `compileAst()` tetap menjadi padanan satu langkah |

```php
use function TailwindPHP\compile;

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

## Caching

`tw::generate()` dapat menyimpan CSS hasil kompilasi ke disk sehingga input identik melewati kompilasi ulang.

| Opsi | Tipe | Default | Tujuan |
|---|---|---|---|
| `cache` | `bool \| string` | `false` | `true` mengaktifkan direktori default; string jalur menggunakan lokasi tersebut untuk cache |
| `cacheTtl` | `int` | tidak ada | Masa berlaku cache dalam detik; entri kedaluwarsa dikompilasi ulang |

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

Kunci cache diturunkan dari **konten**, **konfigurasi CSS**, dan opsi **minify**, sehingga input berbeda menghasilkan file cache berbeda. Hapus entri dengan [`tw::clearCache()`](#twclearcache) atau fungsi `TailwindPHP\clearCache()` mandiri.

Untuk panduan lebih mendalam, lihat [Caching & minifikasi](https://tailwindphp.inline0.dev/id/docs/advanced/caching).