# Performa & Pengujian

TailwindPHP mengutamakan kebenaran. Jika perubahan khusus PHP mempercepat proses tanpa mengubah keluaran, perubahan itu diterapkan dan diberi penanda `@port-deviation:performance`. Kesetaraan dengan TailwindCSS tidak diasumsikan — hal itu terus diverifikasi menggunakan rangkaian pengujian milik Tailwind sendiri.

## Performa

Port PHP memprioritaskan kesesuaian keluaran TailwindCSS daripada throughput mentah, dan versi asli TypeScript tetap lebih cepat — JIT milik V8 mengompilasi jalur yang sering digunakan menjadi kode native dengan cara yang tidak dapat ditandingi PHP. Untuk CSS yang dibuat per permintaan atau per halaman, gunakan kembali satu compiler (lihat [generateExact()](https://tailwindphp.inline0.dev/id/docs/api#accumulating-vs-exact-generation)) dan simpan status pembuatannya dengan [`stateCacheFile`](https://tailwindphp.inline0.dev/id/docs/advanced/caching#compiler-state-cache).

Beberapa jalur yang sering digunakan memiliki optimasi yang disetel secara manual dan **mempertahankan keluaran identik**:

- **`ast.php` `toCss()`** — mengumpulkan fragmen dalam array lalu melakukan `implode` sekali, alih-alih menggabungkan string berulang kali, serta menggunakan string indentasi yang telah dihitung sebelumnya.
- **`css-parser.php`** — membandingkan karakter secara langsung alih-alih melalui `ord()`, dan melacak panjang buffer alih-alih menghitung ulang `strlen()`.

Keduanya didokumentasikan dengan `@port-deviation:performance` dan dibatasi oleh rangkaian pengujian — keduanya tidak dapat mengubah CSS yang dihasilkan.

### Tolok ukur

Direktori `benchmarks/` berisi perangkat uji perbandingan. Jalankan dengan:

```bash
composer bench         # PHP vs TypeScript
composer bench:save    # write benchmarks/results.json
```

Contoh hasil pada PHP 8.4.5 / Node.js v22.17.0 (Apple M1):

| Tolok ukur | PHP | TypeScript |
|-----------|-----|------------|
| `css-parser` pada preflight.css | ~816 ops/s | ~15.45K ops/s (≈20× lebih cepat) |
| `toCss` | ~65.85K ops/s | ~2.59M ops/s (≈39× lebih cepat) |

TypeScript lebih cepat untuk operasi tingkat rendah ini, sesuai perkiraan. Untuk pembuatan CSS halaman penuh — kasus penggunaan sebenarnya — performa PHP memadai (sekitar 14 ms per halaman dalam uji sampel). Untuk input identik yang berulang, [cache file](https://tailwindphp.inline0.dev/id/docs/advanced/caching) menghilangkan biaya sepenuhnya.

## Pengujian & kesetaraan

Pengujian memastikan port PHP menghasilkan keluaran yang sama dengan TailwindCSS. Dua pendekatan digunakan bersama.

**1. Pengujian berbasis ekstraksi.** Skrip di `test-coverage/` mengurai file `.test.ts` milik TailwindCSS sendiri dan mengekstrak kasus pengujian ke JSON. PHPUnit kemudian menjalankan kasus tersebut melalui TailwindPHP dan membandingkan keluaran dengan CSS yang diharapkan. Karena ekspektasi berasal langsung dari upstream, setiap penyimpangan dalam perilaku PHP akan muncul sebagai kegagalan. Pengujian ini mencakup bagian yang kompleks: utilitas, varian, integrasi, fungsi CSS, dan pengujian `ui.spec` tingkat browser.

**2. Pengujian unit yang diporting secara manual.** File pengujian TypeScript yang lebih sederhana (AST, parsing CSS, escaping, parsing kandidat, parsing nilai, …) langsung diporting ke PHP dan ditempatkan di samping sumbernya sebagai `*.test.php`, dengan struktur dan asersi yang mencerminkan versi aslinya.

Siklusnya adalah **ekstrak → jalankan → verifikasi**: ekstrak ulang dari referensi TailwindCSS terkini, jalankan rangkaian pengujian, dan setiap penyimpangan menyebabkan kegagalan. Ini menjaga port tetap selaras dengan upstream dan memungkinkan pembaruan TailwindCSS divalidasi secara mekanis, bukan melalui pemeriksaan manual. Penyimpangan menyebabkan CI gagal.

```bash
composer extract   # re-extract test cases from the TailwindCSS reference
composer test      # run the full suite
```

Ada **4,427 pengujian yang lulus** per rilis 1.7.0 (referensi TailwindCSS v4.3.3):

| Rangkaian | Pengujian | Sumber |
|-------|-------|--------|
| Rangkaian TailwindCSS hasil ekstraksi (utilities 706, variants 164, index 148, css-functions 64, `ui.spec` 68) | 1,150 | diekstrak dari `.test.ts` / `.spec.ts` |
| Cakupan API (utilities, modifiers, variants, directives, plugins, imports, `@source`, caching, public API) | 2,252 | `tests/` |
| Pengujian unit di samping sumber (parser, AST, candidates, theme, utils, selector parser, transformasi lightningcss, minifier) | 767 | port `*.test.php` dan pengujian khusus PHP |
| CLI (parsing argumen, keluaran, build) | 84 | `tests/Cli*Test.php` |
| Port plugin (typography, forms) | 45 | `*.test.php` di samping plugin |
| Pustaka pendamping (clsx, tailwind-merge, CVA) | 129 | rangkaian referensi |

## Kualitas kode

Pemformatan dan analisis statis dijalankan melalui skrip Composer:

```bash
composer lint      # Pint --test  (check formatting)
composer format    # Pint         (fix formatting)
composer analyse   # PHPStan      (static analysis, level 4)
composer quality   # lint + analyse
```

PHPStan berjalan pada level 4 (`phpstan.neon`), dengan daftar singkat pola yang diabaikan untuk bentuk array dinamis yang digunakan arsitektur berbasis fungsi. Semua file sumber dianalisis; file pengujian dikecualikan.

Untuk melihat struktur yang diverifikasi oleh pengujian ini dan lokasi pencatatan penyimpangan, lihat [Arsitektur](https://tailwindphp.inline0.dev/id/docs/advanced/architecture).