# shikiphp

A shikiphp a [Shiki](https://shiki.style) tisztán PHP nyelven írt portja, annak a szintaxiskiemelőnek, amely a VS Code-éval azonos TextMate nyelvtanokkal és témákkal színezi a kódot. A kódot ugyanazokkal a **TextMate nyelvtanokkal** tokenizálja, és ugyanazokkal a **VS Code témákkal** színezi, amelyeket a Shiki használ, így ugyanazt az HTML állítja elő, mint a Shiki 3.23.0 — teljes egészében PHP nyelven.

Nincs Node-futtatókörnyezet. A `json` és `mbstring` kivételével nincsenek PHP-kiterjesztések. Nincs natív Oniguruma kötés, nincs külön JavaScript folyamat indítása, és nincs hosztolt API sem.

```php
use Shikiphp\Shikiphp;

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

## Miért a shikiphp?

A szerveren végzett szintaxiskiemelés a PHP rendszerben általában három kompromisszum egyikével jár: Node indítása külön folyamatként, hosztolt API meghívása vagy egy, a nyelvet valójában nem értő, reguláris kifejezésekre épülő kiemelő használata. Ezek egyike sem illeszkedik jól a Laravel, WordPress vagy statikus webhelyet készítő buildfolyamatba.

A shikiphp úgy szünteti meg ezt a kompromisszumot, hogy a Shiki valódi feldolgozási folyamatát portolja PHP nyelvre:

- TextMate nyelvtani tokenizer, a [`vscode-textmate`](https://github.com/microsoft/vscode-textmate) hű portja, beágyazott nyelvekkel, injekciókkal és egymásba ágyazott tárolókkal
- VS Code témák feloldása hatókörválasztó-specifikussággal és szülőhatókör-illesztéssel
- Shiki-kompatibilis HTML: kettős világos/sötét témák CSS változókkal, `codeToHast`, transzformátorok (minden hook), díszítések, `colorReplacements`, `structure: 'inline'` és ANSI (`lang: 'ansi'`) kiemelés
- a **teljes Shiki csomag** — minden `tm-grammars` nyelv (235, valamint az általuk beágyazott 18 segédnyelvtan) és mind a `tm-themes` téma (65)

## Összevetve ezzel: Shiki 3.23.0

A kimenet nem csupán „elég közeli”: egy rögzített Shiki-kiadással ellenőrizzük.

| Csomag | Verzió | Felhasználás |
| --- | --- | --- |
| `shiki` | 3.23.0 | referencia, a saját JavaScript reguláriskifejezés-motorjával futtatva |
| `tm-grammars` | 1.31.15 | beépített nyelvtanok |
| `tm-themes` | 1.12.2 | beépített témák |
| `@shikijs/transformers` | 4.2.0 | transzformátorok egyezőségi tesztjei |

Maga a Shiki a referencia. A regressziós tesztkészlet **214 forgatókönyvet** tartalmaz; mindegyik egy mintát, egy nyelvet és egy témát használ alapértelmezett beállításokkal. Minden forgatókönyvet a Shiki és a shikiphp is kiemel, és a két HTML karakterláncnak a kezdő és záró szóközök levágása után pontosan egyeznie kell. Együtt a forgatókönyvek a beépített 253 nyelvtanok 167 részét, a `lang: 'ansi'` nyelvet és mind a 65 témát lefedik. A beállításokat (`structure`, `tabindex`, `colorReplacements`, kettős témák, `defaultColor` és a többi), a `codeToTokensWithThemes` funkciót és a beépített transzformátorokat külön egyezőségi tesztek ellenőrzik; ezek elvárt kimenetét ugyanazon Shiki-verziókkal rögzítették.

Ennek két korlátja van. A Shiki alapértelmezett motorja Oniguruma WebAssemblyre fordítva, a referencia viszont a Shiki JavaScript reguláriskifejezés-motorját használja, amelyre a shikiphp portol. A későbbi Shiki-kiadásokat (a 4.x sorozatot) még nem ellenőrizték.

## Működés

A shikiphp egy külső forrásból beemelt, tisztán PHP nyelvű **JavaScript reguláriskifejezés-motorra** épül, amelyet a [`inline0/phasis`](https://github.com/inline0/phasis) biztosít; bemenetét a [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es) portja szolgáltatja PHP nyelven. A Shiki JavaScript reguláriskifejezés-motorja a TextMate nyelvtanok Oniguruma mintáit JavaScript `RegExp` formára alakítja, ezért a JS reguláriskifejezés-motor természetes alap: így a shikiphp kimenete pozícióról pozícióra egyeztethető ezzel a motorral.

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

A teljes feldolgozási folyamatról lásd: [Architektúra](https://shikiphp.inline0.dev/hu/docs/architecture).

## Követelmények

- PHP 8.2 vagy újabb (a CI a tesztcsomagot PHP 8.4 verzióval futtatja)
- `ext-json` és `ext-mbstring` (szinte minden PHP build tartalmazza őket)

## Merre tovább?

- [Első lépések](https://shikiphp.inline0.dev/hu/docs/getting-started) — telepítse, és jelenítse meg az első blokkot.
- [API](https://shikiphp.inline0.dev/hu/docs/api) — a teljes metóduskészlet.
- [Beállítások](https://shikiphp.inline0.dev/hu/docs/options) — az összes, `codeToHtml` által elfogadott beállítás.
- [Transzformátorok](https://shikiphp.inline0.dev/hu/docs/transformers) — a hook-folyamat és a beépített elemek.
- [CLI](https://shikiphp.inline0.dev/hu/docs/cli) — `bin/shikiphp highlight`, `langs` és `themes`.

## Licenc

MIT, szerzői jog: inline0. A beépített TextMate nyelvtanokra és témákra a forrásprojektek licencei érvényesek.