# Kompatibilitas & Pembaruan

Halaman ini merangkum hal-hal yang perlu diketahui sebelum memperbarui atau mengandalkan keluaran yang persis: persyaratan runtime, rilis TailwindCSS yang diikuti port ini, perbedaan yang memang ada antara TailwindPHP dan TailwindCSS, serta catatan untuk setiap rilis. Riwayat lengkap tersedia di [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## Persyaratan

- **PHP 8.2 atau lebih baru.** Rangkaian pengujian berjalan pada PHP 8.2, 8.3, dan 8.4.
- **Ekstensi `ctype` dan `mbstring`.** Compiler memanggil `ctype_*` dan `mb_chr()`. Keduanya disertakan dalam sebagian besar build PHP dan image resmi Docker, tetapi `composer.json` belum mendeklarasikannya ([#11](https://github.com/inline0/tailwindphp/issues/11)), jadi build tanpa ekstensi tersebut akan memasang paket tetapi gagal saat runtime.
- **Opsional: `pcntl`** memungkinkan mode CLI `--watch` berhenti dengan bersih pada `SIGINT`/`SIGTERM`. Tanpanya, mode watch tetap berfungsi.

Tidak menggunakan Node.js, FFI, ataupun biner native.

## Rilis TailwindCSS yang diikuti

Rilis 1.7.0 mengikuti **TailwindCSS v4.3.3**. Repositori upstream dipatok sebagai submodul git di `reference/tailwindcss`, rangkaian pengujiannya diambil dari checkout yang dipatok tersebut, dan pengujian 4,427 dijalankan pada setiap push (lihat [Pengujian & performa](https://tailwindphp.inline0.dev/id/docs/advanced/performance)). Plugin yang di-porting mengikuti `@tailwindcss/typography` dan `@tailwindcss/forms`, sedangkan utilitas kelas mengikuti clsx, tailwind-merge, dan CVA; semuanya dipatok dengan cara yang sama.

## Perbedaan yang diketahui dari TailwindCSS

### Detail serialisasi

CSS yang dihasilkan cocok dengan rangkaian pengujian referensi. Beberapa detail serialisasi berbeda dari hasil yang dicetak TailwindCSS CLI, tetapi tidak ada yang mengubah cascade:

- Prefiks vendor: jika referensi menghasilkan baris `-webkit-*` yang ditulis dan baris hasil pembuatan, TailwindPHP menghasilkan satu baris.
- Pseudo-element yang diturunkan levelnya (`::file-selector-button`, `::-webkit-datetime-edit-*`) tetap berada dalam daftar selector yang ditulis, alih-alih dipecah menjadi satu aturan untuk setiap pseudo-element.
- String berpetik tunggal yang ditulis tetap berpetik tunggal (`'Segoe UI'`), alih-alih dinormalisasi menjadi petik ganda.
- Properti longhand yang muncul bersamaan tidak digabung menjadi properti singkatan (keluaran Tailwind sendiri tidak memerlukannya).
- `.p-0` mempertahankan `padding: 0px` ketika referensi CLI menghasilkan `padding: 0`, karena korpus pengujian yang diekstrak mematok bentuk `0px`. Minifier mempersingkatnya menjadi `0`.

### Tidak disertakan

TailwindPHP adalah compiler CSS. Compiler ini tidak menyertakan alat editor dari ekosistem Tailwind (IntelliSense, pelengkapan otomatis, pengurutan kelas) maupun source map, sehingga CLI tidak memiliki opsi `--map`.

### Pemindaian konten

`tw::generate()` dan `TailwindCompiler::generate()` hanya membaca nama kelas dari atribut `class` dan `className`. Untuk nama kelas yang tersimpan dalam string PHP atau JavaScript, gunakan [`tw::extractCandidatesFromStrings()`](https://tailwindphp.inline0.dev/id/docs/api#twextractcandidatesfromstrings) atau `@source inline("…")`. Bentuk jalur `@source` diabaikan oleh API dan hanya sebagian didukung oleh CLI (lihat di bawah).

### Masalah yang diketahui pada rilis saat ini

| Area | Perilaku saat ini | Masalah |
|---|---|---|
| CLI `@source` | Jalur dan glob tidak diterapkan; direktori file masukan yang dipindai, dan `@source not` tidak mengecualikan apa pun. Lihat [Yang dipindai CLI](https://tailwindphp.inline0.dev/id/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Melakukan minifikasi, seperti `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Opsi panjang CLI | `--input file.css` (dipisahkan spasi) diabaikan; gunakan `--input=file.css` atau `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Varian plugin | Varian `addVariant()`/`matchVariant()` dan pengubah elemen tipografi (`prose-headings:` …) dikompilasi tanpa selector | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Mixin `@apply` | `@apply --my-mixin;` dihapus alih-alih diteruskan | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Impor referensi | Keluaran kosong jika impor referensi mendahului impor utilitas; `@import "tailwindcss" reference` tidak berpengaruh | [#14](https://github.com/inline0/tailwindphp/issues/14) |

## Catatan pembaruan

### 1.7.0

- **Keluaran berubah pada tingkat byte** dibandingkan dengan 1.6.x, meski tetap setara secara fungsional dengan referensi TailwindCSS v4.3.3. Beberapa perubahan yang terlihat:
  - Pengali spasi: `p-1` menghasilkan `padding: var(--spacing)` alih-alih `calc()`, dan pengali `0` menghasilkan panjang nol biasa.
  - Pecahan diubah menjadi persentase: `w-1/2` menghasilkan `width: 50%`.
  - Warna: kecerahan `oklch()`/`oklab()` diserialisasi sebagai persentase (`oklch(62.3% .214 259.815)`), `white` dan `black` dipersingkat menjadi `#fff` dan `#000`.
  - Pseudo-element CSS2 diserialisasi dengan satu titik dua (`:before`, `:after`, `:first-letter`, `:first-line`).
  - Aturan `@media`/`@supports`/`@container` bersarang diratakan di tempatnya sesuai urutan sumber, alih-alih dipindahkan ke akhir; deklarasi diurutkan ulang sesuai urutan lightningcss; deklarasi duplikat yang tertimpa dihapus.
- **Cache berdasarkan keluaran akan perlu dibuat ulang satu kali.** Kunci cache file milik `tw::generate()` tidak menyertakan versi TailwindPHP, jadi jalankan `tw::clearCache()` (atau direktori yang Anda berikan sebagai `cache`) setelah memperbarui. [cache status compiler](https://tailwindphp.inline0.dev/id/docs/advanced/caching#compiler-state-cache) akan membatalkan cache secara otomatis.
- **Baru:** `@variant` dalam CSS penulis, mixin CSS di `@apply`, `@media reference` dan `@import "…" reference`, mesin `--value()`/`--modifier()` lengkap untuk `@utility` fungsional, validasi nama `@utility` yang lebih ketat, dan opsi `tw::compile()` untuk `polyfills`.

### 1.6.1

- **Baru:** utilitas `container` (`width: 100%` ditambah satu `max-width` untuk setiap breakpoint).
- Variabel `--tw-*` gabungan (translate, scale, rotate, skew, filter, dan lainnya) kini terdaftar dengan `@property`, sehingga stylesheet memperoleh aturan `@property` tersebut dan transformasi seperti `translate-x-7` berlaku di browser.

### 1.6.0

- **Baru:** cache status compiler persisten (`stateCacheFile` pada `tw::compile()` dan `TailwindCompiler`, `StateCache\compileCssCached()`), serta fungsi `parseCssState()`/`finalizeCssState()`/`compileParsed()` yang dipisah. Pemanggilan yang sudah ada tetap berperilaku persis seperti sebelumnya.

### 1.5.0

- Subkelas `TailwindCompiler` yang menimpa `generate()` atau `css()` harus menambahkan parameter opsional `bool $minify = false`; PHP menolak penimpaan yang menghilangkan parameter opsional milik kelas induk.
- Keluaran yang diminifikasi berasal dari serializer, jadi byte hasil minifikasi sedikit berbeda dari 1.4.x (cache berdasarkan keluaran minifikasi perlu dibuat ulang satu kali).
- **Baru:** `generateExact()` dan `cssExact()` untuk CSS per halaman dari satu compiler berumur panjang.