# shikiphp

shikiphp je čista vrata PHP za [označevalnik sintakse](https://shiki.style) Shiki, ki obarva kodo z enakimi slovnicami TextMate in temami kot VS Code. Kodo razčleni na žetone z enakimi **slovnicami TextMate** in jo obarva z enakimi **temami VS Code**, ki jih uporablja Shiki, ter ustvari enak HTML kot Shiki 3.23.0 — v celoti v PHP.

Brez izvajalnega okolja Node. Brez razširitev PHP razen `json` in `mbstring`. Brez izvorne vezave Oniguruma. Brez zaganjanja zunanjega procesa JavaScript in brez gostovanega API.

```php
use Shikiphp\Shikiphp;

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

## Zakaj shikiphp

Označevanje sintakse na strežniku v PHP običajno zahteva enega od treh kompromisov: zagon Node, klic gostovanega API ali zadovoljitev z označevalnikom na podlagi regularnih izrazov, ki jezika v resnici ne razume. Nobena od teh možnosti se dobro ne prilega gradnji za Laravel, WordPress ali statično spletno mesto.

shikiphp odpravi kompromis tako, da dejanski cevovod iz Shiki prenese v PHP:

- tokenizator slovnice TextMate (zvest prenos
  [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), vključno z
  vdelanimi jeziki, injekcijami in ugnezdenimi repozitoriji
- razreševanje tem VS Code s specifičnostjo izbirnika obsega in ujemanjem nadrejenih obsegov
- izris Shiki, združljiv s HTML: svetle in temne teme prek spremenljivk CSS, `codeToHast`, pretvorniki (vse zanke), okraski, `colorReplacements`, `structure: 'inline'` in označevanje ANSI (`lang: 'ansi'`)
- **celoten paket Shiki** — vsi jeziki `tm-grammars` (235 in 18 pomožnih slovnic, ki jih vdelujejo) ter vseh `tm-themes` tem (65)

## Primerjano z Shiki 3.23.0

Izhod ni »dovolj podoben«: preverjen je glede na določeno izdajo Shiki.

| Paket | Različica | Namen uporabe |
| --- | --- | --- |
| `shiki` | 3.23.0 | referenčni vir, zagnan z njegovim pogonom regularnih izrazov JavaScript |
| `tm-grammars` | 1.31.15 | vgrajene slovnice |
| `tm-themes` | 1.12.2 | vgrajene teme |
| `@shikijs/transformers` | 4.2.0 | testi enakovrednosti pretvornikov |

Sam Shiki je referenčni vir. Preizkusno ogrodje za regresije vsebuje **214 scenarijev**, v vsakem pa vzorec za en jezik in eno temo s privzetimi možnostmi. Vsak scenarij označita Shiki in shikiphp, njuna niza HTML pa morata biti enaka, ko odstranimo začetne in končne presledke. Skupaj scenariji pokrivajo 167 od 253 vgrajenih slovnic, `lang: 'ansi'` in vseh 65 tem. Možnosti (`structure`, `tabindex`, `colorReplacements`, dve temi, `defaultColor` in druge), `codeToTokensWithThemes` ter vgrajeni pretvorniki so zajeti v ločenih testih enakovrednosti; pričakovani izhod je bil zajet iz istih različic Shiki.

Iz tega sledita dve omejitvi. Privzeti pogon Shiki je Oniguruma, preveden v WebAssembly, referenčni vir pa namesto njega uporablja pogon regularnih izrazov Shiki JavaScript, ki ga prenaša shikiphp. Preverjene niso bile niti poznejše izdaje Shiki (linija 4.x).

## Kako deluje

shikiphp temelji na vključenem pogonu za **regularne izraze JavaScript**, v celoti napisanem v PHP, iz [`inline0/phasis`](https://github.com/inline0/phasis), ki ga napaja prenos [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es) v PHP. Pogon za regularne izraze JavaScript v Shiki pretvarja vzorce Oniguruma iz slovnic TextMate v JavaScript `RegExp`, zato je pogon za regularne izraze JS naravna osnova: shikiphp omogoča ujemanje z izhodom tega pogona pri vsakem odmiku.

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

Za celoten potek glejte [Arhitektura](https://shikiphp.inline0.dev/sl/docs/architecture).

## Zahteve

- PHP 8.2 ali novejši (CI izvaja testno zbirko na PHP 8.4)
- `ext-json` in `ext-mbstring` (priložena sta skoraj vsaki različici PHP)

## Kam naprej

- [Začetek](https://shikiphp.inline0.dev/sl/docs/getting-started) — namestite in izrišite svoj prvi blok.
- [API](https://shikiphp.inline0.dev/sl/docs/api) — celoten nabor metod.
- [Možnosti](https://shikiphp.inline0.dev/sl/docs/options) — vse možnosti, ki jih sprejema `codeToHtml`.
- [Transformatorji](https://shikiphp.inline0.dev/sl/docs/transformers) — cevovod priklopov in vgrajeni elementi.
- [CLI](https://shikiphp.inline0.dev/sl/docs/cli) — `bin/shikiphp highlight`, `langs` in `themes`.

## Licenca

MIT, avtorske pravice inline0. Priložene slovnice in teme TextMate ohranjajo svoje
izvorne licence.