# Caching & Minifikasi

Tiga kebutuhan produksi muncul di ujung pipeline: menghindari kompilasi ulang masukan yang identik, menghindari biaya membangun compiler pada setiap permintaan, dan mengecilkan CSS yang dihasilkan. Ketiganya adalah helper di sisi PHP yang mendukung compiler.

## Caching

Pembuatan CSS menjalankan seluruh pipeline pada setiap pemanggilan. Untuk konten yang tidak berubah antarpermintaan, cache berbasis file menyimpan hasil ke disk dan menyajikannya pada pemanggilan berikutnya.

Berikan `cache` ke `tw::generate()`—`true` untuk direktori default, atau string jalur untuk direktori khusus:

```php
use TailwindPHP\tw;

// Cache to the default directory: sys_get_temp_dir() . '/tailwindphp'
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
]);

// Cache to a custom directory
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => '/path/to/cache',
]);

// With a time-to-live (seconds)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'cache' => true,
    'cacheTtl' => 3600, // expire after 1 hour
]);
```

Direktori cache dibuat otomatis jika belum ada.

### Kunci cache

Kunci diturunkan dari **konten**, **konfigurasi CSS**, dan flag **minify**—lalu di-hash menjadi nama file `tailwind_<hash>.css`. Setiap perubahan pada markup, masukan CSS, atau status minifikasi menghasilkan kunci yang berbeda, sehingga nama file pun berbeda.

Konfigurasi CSS dalam kunci mencakup `css` inline beserta isi file yang disebut dalam `importPaths`. Dua jenis masukan tidak disertakan: file yang dimuat melalui `@import` bersarang di dalam file tersebut, dan versi TailwindPHP. Hapus cache setelah mengedit impor bersarang atau memperbarui paket, jika tidak keluaran lama akan terus disajikan.

### Masa berlaku

`cacheTtl` adalah masa berlaku dalam detik. Saat cache cocok, waktu modifikasi file dibandingkan dengan waktu saat ini; jika file lebih lama daripada `cacheTtl`, cache dianggap tidak cocok dan file dikompilasi ulang. Jika `cacheTtl` tidak ditentukan, entri tidak pernah kedaluwarsa—hapus secara manual.

### Menghapus cache

`tw::clearCache()` (atau fungsi `clearCache()`) menghapus file `tailwind_*.css` dari direktori cache dan mengembalikan jumlah file yang dihapus.

```php
use TailwindPHP\tw;
use function TailwindPHP\clearCache;

$deleted = tw::clearCache();                  // default directory
$deleted = tw::clearCache('/path/to/cache');  // custom directory
clearCache('/path/to/cache');                 // function form
```

## Cache status compiler

Cache keluaran hanya membantu jika konten yang sama muncul kembali. Jika konten berubah pada setiap pemanggilan, bagian yang mahal adalah membangun compiler itu sendiri: menyelesaikan `@import "tailwindcss"`, mengurai resource yang disertakan, dan mengumpulkan tema. Tahap ini hanya bergantung pada masukan CSS, jadi statusnya dapat disimpan dan digunakan kembali.

Berikan `stateCacheFile` ke `tw::compile()` (atau `new TailwindCompiler($css, $options)`):

```php
use TailwindPHP\tw;

$compiler = tw::compile($themeCss, [
    'stateCacheFile' => __DIR__ . '/cache/tailwind-state.php',
]);

$css = $compiler->generateExact($html, true);
```

Pada konstruksi pertama, status ditulis ke jalur tersebut sebagai file PHP biasa yang dapat digunakan bersama oleh OPcache di antara permintaan; konstruksi berikutnya memuat file itu alih-alih mengurai ulang. Keluaran identik byte demi byte dengan compiler tanpa cache.

- File divalidasi berdasarkan sidik jari mesin (ukuran dan mtime sumber serta resource milik TailwindPHP), kunci yang diturunkan dari masukan CSS dan opsi `base` serta `importSearchPaths`, dan ukuran serta mtime setiap file yang diimpor oleh masukan tersebut. Ketidakcocokan akan membangun ulang dan menulis ulang file, jadi memperbarui TailwindPHP atau mengedit file yang diimpor tidak memerlukan langkah manual.
- Anda mengelola jalurnya: gunakan satu file untuk setiap masukan CSS yang berbeda, di direktori yang dapat ditulisi server web. Penulisan dilakukan secara atomik (file sementara ditambah `rename()`).
- Masukan yang menggunakan `importResolver` khusus melewati cache karena perilaku resolver tidak dapat dibuatkan sidik jari.
- Cache yang sama tersedia untuk `compile()` API tingkat lebih rendah sebagai `TailwindPHP\StateCache\compileCssCached($css, $cacheFile, $options)`.

`tw::generate()` tidak menerima `stateCacheFile`; compiler baru dibuat pada setiap pemanggilan. Gunakan instans compiler jika biaya konstruksi menjadi pertimbangan.

## Minifikasi

Minifikasi mengecilkan keluaran untuk produksi. Flag `minify` menghasilkan CSS yang diminifikasi langsung selama serialisasi, sehingga menjadi jalur tercepat dan paling presisi; `tw::minify()` menjalankan minifier berbasis string (`src/_tailwindphp/CssMinifier.php`) pada string CSS yang sudah ada:

```php
use TailwindPHP\tw;

// Minify during generation (serializer path, preferred)
$css = tw::generate([
    'content' => '<div class="flex p-4">Hello</div>',
    'minify' => true,
]);

// Or minify an existing string (string-based post-pass)
$css = tw::generate('<div class="flex p-4">Hello</div>');
$minified = tw::minify($css);
```

Kedua jalur menghasilkan struktur yang setara, tetapi byte-nya tidak identik. Jalur serializer mempertahankan selector `:not()` turunan yang digabungkan oleh pemrosesan string, jadi utamakan flag `minify` untuk keluaran yang dihasilkan dan gunakan `tw::minify()` untuk CSS yang diterima sebagai string.

### Fungsinya

Kedua jalur menerapkan rangkaian pengurangan ukuran yang sama:

| Langkah | Dampak |
|------|--------|
| Hapus komentar | Menghapus blok `/* … */` |
| Rapikan spasi kosong | Merapatkan rangkaian spasi kosong dan menghapusnya di sekitar `{ } ; : ,` serta kombinator selector |
| Persingkat warna hex | `#ffffff` → `#fff`, `#aabbcc` → `#abc` |
| Hapus satuan nol | `0px` → `0` (mempertahankan nilai waktu `0s`/`0ms`) |
| Persingkat font-weight | `font-weight:normal` → `400`, `font-weight:bold` → `700` |
| Hapus aturan kosong | Menghapus selector dengan blok deklarasi kosong |

Secara sengaja, proses ini **tidak** menggabungkan selector duplikat atau properti singkatan—keduanya mempersulit proses debug dan dapat memengaruhi cascade.

### CLI: `--minify` dibanding `--optimize`

[CLI](https://tailwindphp.inline0.dev/id/docs/cli) menyediakan jalur minifikasi serializer melalui dua flag:

```bash
# Optimize and minify (smallest output)
tailwindphp -i ./src/app.css -o ./dist/styles.css --minify   # or -m

# Meant to optimize without minifying
tailwindphp -i ./src/app.css -o ./dist/styles.css --optimize
```

Pada rilis saat ini, `--optimize` juga melakukan minifikasi, jadi kedua perintah menulis byte yang sama ([#9](https://github.com/inline0/tailwindphp/issues/9)). Transformasi setara lightningcss berjalan pada setiap build, sehingga keluaran biasa (tanpa flag) sudah optimal dan mudah dibaca.

Untuk bagian lain dari API publik—`tw::generate()`, `tw::compile()`, metode inspeksi, dan format masukan—lihat referensi [API](https://tailwindphp.inline0.dev/id/docs/api).