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:

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.

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

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:

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:

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

CLI: --minify dibanding --optimize

CLI menyediakan jalur minifikasi serializer melalui dua flag:

# 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). 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.