# shikiphp

shikiphp ir tīrs PHP ports no [Shiki](https://shiki.style) — sintakses izcēlāja, kas iekrāso kodu, izmantojot tās pašas TextMate gramatikas un tēmas, ko VS Code. Tas sadala kodu marķieros, izmantojot tās pašas **TextMate gramatikas**, un iekrāso to ar tām pašām **VS Code tēmām**, ko izmanto Shiki, tādējādi iegūstot tādu pašu HTML kā Shiki 3.23.0 — pilnībā PHP vidē.

Nav nepieciešama Node izpildvide. Nav PHP paplašinājumu, izņemot `json` un `mbstring`. Nav vietējā Oniguruma saistījuma. Nav jāpalaiž atsevišķs JavaScript process un nav nepieciešams mitināts API.

```php
use Shikiphp\Shikiphp;

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

## Kāpēc shikiphp

Sintakses izcelšanai servera pusē PHP parasti jāpieņem viens no trim kompromisiem: jāpalaiž Node, jāizsauc mitināts API vai jāiztiek ar uz regex balstītu izcēlāju, kas valodu patiesībā nesaprot. Neviens no šiem variantiem labi neiederas Laravel, WordPress vai statiskas vietnes būvēšanas procesā.

shikiphp novērš kompromisus, pārnesot Shiki īsto apstrādes procesu uz PHP:

- TextMate gramatiku marķieru ģenerētājs (uzticams ports no [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), tostarp iegultās valodas, injekcijas un ligzdotas krātuves
- VS Code tēmu atrisināšana pēc tvēruma atlasītāju specifiskuma, ņemot vērā arī vecāktvērumus
- ar Shiki saderīga HTML: gaišās un tumšās tēmas ar CSS mainīgajiem, `codeToHast`, pārveidotājiem (visi āķi), dekorācijām, `colorReplacements`, `structure: 'inline'` un ANSI (`lang: 'ansi'`) izcelšanu
- **pilns Shiki komplekts** — visas `tm-grammars` valodas (235, kā arī 18 palīggramatikas, ko tās iegulst) un visas `tm-themes` tēmas (65)

## Salīdzināts ar Shiki 3.23.0

Izvade ir pārbaudīta pret piesaistītu Shiki laidienu, un tai nav pieļaujamas pat nelielas atšķirības.

| Pakotne | Versija | Izmantojums |
| --- | --- | --- |
| `shiki` | 3.23.0 | etalons, kas darbojas ar savu JavaScript regex dzinēju |
| `tm-grammars` | 1.31.15 | komplektā iekļautās gramatikas |
| `tm-themes` | 1.12.2 | komplektā iekļautās tēmas |
| `@shikijs/transformers` | 4.2.0 | pārveidotāju atbilstības testi |

Pats Shiki ir etalons. Regresiju testu kopā ir **214 scenāriji** — katrā ir paraugs vienā valodā un vienā tēmā ar noklusējuma opcijām. Katru scenāriju izceļ gan Shiki, gan shikiphp, un abām HTML virknēm pēc atstarpju apgriešanas sākumā un beigās ir jābūt identiskām. Kopā scenāriji aptver 167 no 253 komplektā iekļautajām gramatikām, `lang: 'ansi'` un visas 65 tēmas. Opcijas (`structure`, `tabindex`, `colorReplacements`, divas tēmas, `defaultColor` un citas), `codeToTokensWithThemes` un iebūvētie pārveidotāji tiek pārbaudīti atsevišķos atbilstības testos, kuru sagaidāmais rezultāts iegūts no tām pašām Shiki versijām.

No tā izriet divi ierobežojumi. Shiki noklusējuma dzinējs ir Oniguruma, kas kompilēts uz WebAssembly, bet etalons izmanto citu dzinēju — Shiki JavaScript regex dzinēju, kuru pārnes shikiphp. Turklāt vēlākie Shiki laidieni (4.x atzars) nav pārbaudīti.

## Kā tas darbojas

shikiphp izmanto pārdevēja piegādātu tīru PHP **JavaScript regex dzinēju** no [`inline0/phasis`](https://github.com/inline0/phasis), kura pamatā ir PHP ports no [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Shiki JavaScript regex dzinējs pārvērš TextMate gramatiku Oniguruma rakstus par JavaScript `RegExp`, tāpēc JS regex dzinējs ir dabiska platforma — tas ļauj shikiphp salīdzināt šī dzinēja izvadi ar precīzu nobīdi.

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

Pilnu apstrādes procesu skatiet sadaļā [Arhitektūra](https://shikiphp.inline0.dev/lv/docs/architecture).

## Prasības

- PHP 8.2 vai jaunāka versija (CI testu kopu palaiž ar PHP 8.4)
- `ext-json` un `ext-mbstring` (abi ir iekļauti gandrīz katrā PHP būvējumā)

## Kurp doties tālāk

- [Darba sākšana](https://shikiphp.inline0.dev/lv/docs/getting-started) — instalējiet un attēlojiet savu pirmo bloku.
- [API](https://shikiphp.inline0.dev/lv/docs/api) — visas pieejamās metodes.
- [Opcijas](https://shikiphp.inline0.dev/lv/docs/options) — visas opcijas, ko pieņem `codeToHtml`.
- [Pārveidotāji](https://shikiphp.inline0.dev/lv/docs/transformers) — āķu apstrādes process un iebūvētie pārveidotāji.
- [CLI](https://shikiphp.inline0.dev/lv/docs/cli) — `bin/shikiphp highlight`, `langs` un `themes`.

## Licence

MIT, autortiesības pieder inline0. Komplektā iekļautās TextMate gramatikas un tēmas saglabā sākotnējās licences.