# shikiphp

shikiphp adalah port PHP murni dari [Shiki](https://shiki.style), penyorot sintaks yang mewarnai kode dengan tata bahasa dan tema TextMate yang sama seperti di VS
Code. Kode ditokenisasi dengan **tata bahasa TextMate** yang sama dan diwarnai dengan
**tema VS Code** yang sama dengan yang digunakan Shiki, menghasilkan HTML yang sama seperti Shiki 3.23.0
— sepenuhnya di PHP.

Tanpa runtime Node. Tanpa ekstensi PHP di luar `json` dan `mbstring`. Tanpa binding
Oniguruma native. Tanpa menjalankan proses JavaScript eksternal, dan tanpa API yang di-host.

```php
use Shikiphp\Shikiphp;

echo Shikiphp::codeToHtml(<<<'PHP'
<?php
function greet(string $name): string {
    return "Hello, {$name}!";
}
PHP, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);
```

## Mengapa shikiphp

Penyorotan sintaks yang dirender di server dalam PHP biasanya menuntut salah satu dari tiga
kompromi: menjalankan Node, memanggil API yang di-host, atau menggunakan penyorot berbasis regex
yang sebenarnya tidak memahami bahasa tersebut. Semua itu tidak cocok untuk langkah build
Laravel, WordPress, atau situs statis.

shikiphp menghilangkan kompromi tersebut dengan memindahkan pipeline Shiki yang sebenarnya ke PHP:

- tokenizer tata bahasa TextMate (port setia dari
  [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), termasuk
  bahasa tertanam, injeksi, dan repositori bertingkat
- resolusi tema VS Code dengan spesifisitas pemilih cakupan dan pencocokan cakupan induk
- Shiki-kompatibel HTML: tema terang/gelap ganda melalui variabel CSS, `codeToHast`,
  transformer (setiap hook), dekorasi, `colorReplacements`,
  `structure: 'inline'`, dan penyorotan ANSI (`lang: 'ansi'`)
- **bundle Shiki lengkap** — semua bahasa `tm-grammars` (235, ditambah 18
  tata bahasa pembantu yang disematkannya) dan semua tema `tm-themes` (65)

## Dicocokkan dengan Shiki 3.23.0

Keluarannya bukan sekadar "cukup mirip": keluaran ini diperiksa terhadap rilis Shiki yang dipatok.

| Paket | Versi | Digunakan untuk |
| --- | --- | --- |
| `shiki` | 3.23.0 | oracle, dijalankan dengan mesin regex JavaScript-nya |
| `tm-grammars` | 1.31.15 | tata bahasa yang disertakan |
| `tm-themes` | 1.12.2 | tema yang disertakan |
| `@shikijs/transformers` | 4.2.0 | pengujian kesetaraan transformer |

Shiki sendiri adalah oracle-nya. Harness regresi berisi **214 skenario**,
masing-masing berupa sampel dalam satu bahasa dan satu tema dengan opsi bawaan. Setiap
skenario disorot oleh Shiki dan shikiphp, dan kedua string HTML harus
identik setelah spasi di awal dan akhir dihapus. Secara keseluruhan,
skenario mencakup 167 dari 253 tata bahasa yang disertakan, `lang: 'ansi'`, dan semua 65
tema. Opsi (`structure`, `tabindex`, `colorReplacements`, tema ganda,
`defaultColor` dan lainnya), `codeToTokensWithThemes`, serta transformer bawaan diuji dalam pengujian
kesetaraan terpisah dengan keluaran yang diharapkan diambil dari versi Shiki yang sama.

Ada dua batasan yang mengikuti hal tersebut. Mesin bawaan Shiki adalah Oniguruma yang dikompilasi ke
WebAssembly, sedangkan oracle menggunakan mesin regex JavaScript milik Shiki,
yaitu mesin yang digunakan port shikiphp. Rilis Shiki berikutnya (seri 4.x) belum
diperiksa.

## Cara kerjanya

shikiphp dibangun di atas **mesin regex JavaScript** murni PHP yang disertakan dari
[`inline0/phasis`](https://github.com/inline0/phasis), dengan masukan berupa port PHP dari
[`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Mesin regex JavaScript milik Shiki mengubah
pola Oniguruma dalam tata bahasa TextMate menjadi JavaScript `RegExp`, jadi mesin regex JS
adalah dasar yang tepat — mesin ini memungkinkan shikiphp mencocokkan keluaran mesin tersebut secara presisi pada setiap offset.

```
code → grammar tokenizer → theme resolver → themed tokens → HTML
              │
              └─ OnigScanner → PatternConverter (oniguruma-to-es) → Shikiphp\Regex (JS RegExp engine)
```

Lihat [Arsitektur](https://shikiphp.inline0.dev/id/docs/architecture) untuk pipeline lengkapnya.

## Persyaratan

- PHP 8.2 atau lebih baru (CI menjalankan rangkaian pengujian pada PHP 8.4)
- `ext-json` dan `ext-mbstring` (keduanya disertakan di hampir setiap build PHP)

## Langkah selanjutnya

- [Memulai](https://shikiphp.inline0.dev/id/docs/getting-started) — instal dan buat blok pertama Anda.
- [API](https://shikiphp.inline0.dev/id/docs/api) — seluruh permukaan metode.
- [Opsi](https://shikiphp.inline0.dev/id/docs/options) — setiap opsi yang diterima `codeToHtml`.
- [Transformer](https://shikiphp.inline0.dev/id/docs/transformers) — pipeline hook dan transformer bawaan.
- [CLI](https://shikiphp.inline0.dev/id/docs/cli) — `bin/shikiphp highlight`, `langs`, dan `themes`.

## Lisensi

MIT, hak cipta inline0. Tata bahasa dan tema TextMate yang disertakan tetap menggunakan
lisensi upstream masing-masing.