# shikiphp

shikiphp, kodu VS Code ile aynı TextMate dilbilgileri ve temalarla renklendiren sözdizimi vurgulayıcısı [Shiki](https://shiki.style) öğesinin saf bir PHP uyarlamasıdır. Kod, TextMate dilbilgileriyle belirteçlere ayrılır ve Shiki öğesinin kullandığı VS Code temalarıyla renklendirilir; böylece Shiki 3.23.0 ile aynı HTML üretilir — tümü PHP içinde.

Node çalışma zamanı yok. `json` ve `mbstring` dışında PHP uzantısı yok. Yerel Oniguruma bağlaması yok. JavaScript sürecine dış çağrı yok, barındırılan API de yok.

```php
use Shikiphp\Shikiphp;

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

## Neden shikiphp

PHP içinde sunucu tarafında oluşturulan sözdizimi vurgulama genellikle üç ödünden birini gerektirir: Node çalıştırmak, barındırılan bir API çağırmak veya dili gerçekten anlamayan düzenli ifade tabanlı bir vurgulayıcı kullanmak. Bunların hiçbiri Laravel, WordPress ya da statik site derleme adımına tam uymaz.

shikiphp, Shiki öğesinin gerçek işlem hattını PHP diline taşıyarak bu ödünü ortadan kaldırır:

- TextMate dilbilgisi belirteçleyicisi ([`vscode-textmate`](https://github.com/microsoft/vscode-textmate) öğesinin aslına sadık uyarlaması); gömülü diller, eklemeler ve iç içe depolar dahil
- kapsam seçici özgüllüğü ve üst kapsam eşleştirmesiyle VS Code tema çözümleme
- Shiki ile uyumlu HTML: CSS değişkenleriyle açık/koyu çift temalar, `codeToHast`, dönüştürücüler (her kanca), süslemeler, `colorReplacements`, `structure: 'inline'` ve ANSI (`lang: 'ansi'`) vurgulama
- **Shiki paketinin tamamı** — her `tm-grammars` dili (235 ve içlerine ekledikleri 18 yardımcı dilbilgisi) ve her `tm-themes` teması (65)

## Shiki 3.23.0 ile karşılaştırma

Çıktı "yeterince yakın" değildir; sabitlenmiş bir Shiki sürümüyle karşılaştırılır.

| Paket | Sürüm | Kullanım amacı |
| --- | --- | --- |
| `shiki` | 3.23.0 | oracle; JavaScript düzenli ifade motoruyla çalıştırılır |
| `tm-grammars` | 1.31.15 | paketteki dilbilgileri |
| `tm-themes` | 1.12.2 | paketteki temalar |
| `@shikijs/transformers` | 4.2.0 | dönüştürücü uyumluluk testleri |

Oracle, doğrudan Shiki öğesidir. Gerileme test düzeneği, her biri varsayılan seçeneklerle tek bir dil ve tema kullanan bir örnek olan **214 senaryo** içerir. Her senaryo Shiki ve shikiphp ile vurgulanır; baştaki ve sondaki boşluklar kırpıldıktan sonra iki HTML dizgesi aynı olmalıdır. Senaryolar birlikte, paketteki 253 dilbilgisinin 167 tanesini, `lang: 'ansi'` öğesini ve 65 temanın tümünü kapsar. Seçenekler (`structure`, `tabindex`, `colorReplacements`, çift temalar, `defaultColor` ve diğerleri), `codeToTokensWithThemes` ve yerleşik dönüştürücüler, beklenen çıktısı aynı Shiki sürümlerinden alınan ayrı uyumluluk testleriyle kapsanır.

Bundan iki sınırlama doğar. Shiki varsayılan motoru WebAssembly'ye derlenmiş Oniguruma kullanır; oracle ise shikiphp tarafından uyarlanan motor olan Shiki'nin JavaScript düzenli ifade motorunu kullanır. Ayrıca sonraki Shiki sürümleri (4.x serisi) denetlenmemiştir.

## Nasıl çalışır

shikiphp, [`inline0/phasis`](https://github.com/inline0/phasis) kaynaklı, satıcı tarafından dahil edilmiş saf PHP **JavaScript düzenli ifade motoru** üzerine kuruludur; bu motor, [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es) öğesinin PHP uyarlamasıyla beslenir. Shiki öğesinin JavaScript düzenli ifade motoru, TextMate dilbilgilerindeki Oniguruma kalıplarını JavaScript `RegExp` biçimine dönüştürür; bu nedenle saf JS düzenli ifade motoru doğal bir temel oluşturur ve shikiphp bu motorun çıktısıyla her konumda eşleşebilir.

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

Tüm işlem hattı için [Mimari](https://shikiphp.inline0.dev/tr/docs/architecture) bölümüne bakın.

## Gereksinimler

- PHP 8.2 veya üzeri (CI, test paketini PHP 8.4 üzerinde çalıştırır)
- `ext-json` ve `ext-mbstring` (ikisi de neredeyse her PHP derlemesiyle birlikte gelir)

## Sırada ne var

- [Başlangıç](https://shikiphp.inline0.dev/tr/docs/getting-started) — kurulum ve ilk bloğunuzu işleme.
- [API](https://shikiphp.inline0.dev/tr/docs/api) — tüm yöntemler.
- [Seçenekler](https://shikiphp.inline0.dev/tr/docs/options) — `codeToHtml` tarafından kabul edilen her seçenek.
- [Dönüştürücüler](https://shikiphp.inline0.dev/tr/docs/transformers) — kanca işlem hattı ve yerleşik dönüştürücüler.
- [CLI](https://shikiphp.inline0.dev/tr/docs/cli) — `bin/shikiphp highlight`, `langs` ve `themes`.

## Lisans

MIT, telif hakkı inline0'a aittir. Paketteki TextMate dilbilgileri ve temaları, üst projelerinin lisanslarını korur.