# shikiphp

shikiphp je čistý port PHP [Shiki](https://shiki.style), zvýrazňovača syntaxe, ktorý farbí kód pomocou rovnakých gramatík TextMate a tém ako VS Code. Kód tokenizuje pomocou rovnakých **gramatík TextMate** a vykresľuje ho pomocou rovnakých **tém VS Code**, aké používa Shiki, takže vytvára rovnaký HTML ako Shiki 3.23.0 — celý v PHP.

Bez runtime Node.js. Bez rozšírení PHP okrem `json` a `mbstring`. Bez natívnej väzby Oniguruma. Bez spúšťania procesu JavaScript cez shell a bez hostovaného API.

```php
use Shikiphp\Shikiphp;

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

## Prečo shikiphp

Zvýrazňovanie syntaxe vykresľované na serveri v PHP zvyčajne znamená jeden z troch kompromisov: spúšťanie Node.js cez shell, volanie hostovaného API alebo zmierenie sa so zvýrazňovačom založeným na regulárnych výrazoch, ktorý jazyku v skutočnosti nerozumie. Ani jedno z toho sa nedá jednoducho začleniť do Laravel, WordPress ani do kroku zostavenia statického webu.

shikiphp odstraňuje tento kompromis portovaním skutočnej pipeline Shiki do PHP:

- tokenizer gramatík TextMate (verný port
  [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)) vrátane
  vložených jazykov, injekcií a vnorených repozitárov
- rozpoznávanie tém VS Code so špecifickosťou selektorov rozsahu a
  porovnávaním nadradených rozsahov
- Shiki kompatibilné HTML: svetlé/tmavé témy cez premenné CSS,
  `codeToHast`, transformátory (všetky hooky), dekorácie, `colorReplacements`,
  `structure: 'inline'` a zvýrazňovanie ANSI (`lang: 'ansi'`)
- **úplný balík Shiki** — všetky jazyky `tm-grammars` (235 a ďalších 18
  pomocných gramatík, ktoré vkladajú) a všetky témy `tm-themes` (65)

## Porovnávanie s Shiki 3.23.0

Výstup nie je „dosť blízky“: kontroluje sa oproti pripnutému vydaniu Shiki.

| Balík | Verzia | Použitie |
| --- | --- | --- |
| `shiki` | 3.23.0 | referenčná implementácia spustená s jej regexovým jadrom JavaScript |
| `tm-grammars` | 1.31.15 | pribalené gramatiky |
| `tm-themes` | 1.12.2 | pribalené témy |
| `@shikijs/transformers` | 4.2.0 | testy zhody transformátorov |

Samotné Shiki slúži ako referenčná implementácia. Regresný testovací nástroj obsahuje **214 scenárov**, pričom každý predstavuje ukážku v jednom jazyku a jednej téme s predvolenými možnosťami. Každý scenár zvýraznia Shiki aj shikiphp a oba reťazce HTML musia byť po orezaní úvodných a koncových bielych znakov totožné. Scenáre spolu pokrývajú 167 z 253 pribalených gramatík, `lang: 'ansi'` a všetkých 65 tém. Možnosti (`structure`, `tabindex`, `colorReplacements`, dve témy, `defaultColor` a ďalšie), `codeToTokensWithThemes` a vstavané transformátory sa pokrývajú samostatnými testami zhody, ktorých očakávaný výstup bol zachytený z tých istých verzií Shiki.

Z toho vyplývajú dve obmedzenia. Predvolené jadro Shiki je Oniguruma skompilované do WebAssembly, zatiaľ čo referenčná implementácia používa regexové jadro JavaScript od Shiki, ktoré portuje shikiphp. Neskoršie vydania Shiki (rad 4.x) sa nekontrolovali.

## Ako to funguje

shikiphp je postavený na prevzatí čistého PHP **regexového jadra JavaScript** z [`inline0/phasis`](https://github.com/inline0/phasis), ktoré využíva port PHP [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Regexové jadro JavaScript od Shiki prevádza vzory Oniguruma v gramatikách TextMate na JavaScript `RegExp`, takže regexové jadro JS je prirodzeným základom — umožňuje shikiphp porovnávať výstup tohto jadra znak po znaku.

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

Pozrite si [Architektúra](https://shikiphp.inline0.dev/sk/docs/architecture), kde nájdete celý postup spracovania.

## Požiadavky

- PHP 8.2 alebo novší (CI spúšťa testovaciu sadu na PHP 8.4)
- `ext-json` a `ext-mbstring` (sú súčasťou prakticky každého zostavenia PHP)

## Čo ďalej

- [Začíname](https://shikiphp.inline0.dev/sk/docs/getting-started) — nainštalujte a vykreslite svoj prvý blok.
- [API](https://shikiphp.inline0.dev/sk/docs/api) — kompletný prehľad metód.
- [Možnosti](https://shikiphp.inline0.dev/sk/docs/options) — všetky možnosti, ktoré `codeToHtml` prijíma.
- [Transformátory](https://shikiphp.inline0.dev/sk/docs/transformers) — pipeline hookov a vstavané transformátory.
- [CLI](https://shikiphp.inline0.dev/sk/docs/cli) — `bin/shikiphp highlight`, `langs` a `themes`.

## Licencia

MIT, autorské práva inline0. Pribalené gramatiky a témy TextMate si zachovávajú licencie pôvodných projektov.