# shikiphp

shikiphp on teegi [Shiki](https://shiki.style) puhas-PHP port: süntaksi esiletõstja värvib koodi samade TextMate grammatikate ja teemadega nagu VS Code. See tokeniseerib koodi samade **TextMate grammatikatega** ja värvib selle samade **VS Code teemadega**, mida Shiki kasutab, luues sama HTML nagu Shiki 3.23.0 — täielikult PHP-is.

Node'i käituskeskkonda pole. Peale `json` ja `mbstring` pole vaja PHP laiendusi. Natiivset Oniguruma sidumist pole. Välise JavaScript protsessi käivitamist ega majutatud API-i pole.

```php
use Shikiphp\Shikiphp;

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

## Miks shikiphp

Serveris renderdatud süntaksi esiletõstmine PHP-is tähendab tavaliselt üht kolmest kompromissist: Node'i käivitamist, majutatud API-i kasutamist või regulaaravaldisepõhist esiletõstjat, mis keelt tegelikult ei mõista. Ükski neist ei sobi hästi Laravel, WordPress ega staatilise saidi koostamise etappi.

shikiphp kõrvaldab kompromissi, teisendades teegi Shiki tegeliku töötlusahela PHP-ile:

- TextMate grammatika tokeniseerija (teegi [`vscode-textmate`](https://github.com/microsoft/vscode-textmate) täpne port), sealhulgas põimitud keeled, injektsioonid ja pesastatud hoidlad
- VS Code teemalahendus koos ulatuse valija spetsiifilisuse ja ülemulatusse sobitamisega
- Shiki-iga ühilduv HTML: heledad ja tumedad teemad CSS muutujate kaudu, `codeToHast`, teisendajad (kõik haagid), dekoratsioonid, `colorReplacements`, `structure: 'inline'` ja ANSI (`lang: 'ansi'`) esiletõstmine
- **täielik Shiki pakett** — kõik `tm-grammars` keeled (235 ja 18 abigrammatikat, mida need põimivad) ning kõik `tm-themes` teemad (65)

## Võrreldud versioonidega Shiki 3.23.0

Väljund pole lihtsalt „piisavalt lähedane“: seda kontrollitakse kindla Shiki väljalaske alusel.

| Pakett | Versioon | Kasutus |
| --- | --- | --- |
| `shiki` | 3.23.0 | võrdlusalus, käivitatakse selle JavaScript regulaaravaldiste mootoriga |
| `tm-grammars` | 1.31.15 | paketiga kaasas olevad grammatikad |
| `tm-themes` | 1.12.2 | paketiga kaasas olevad teemad |
| `@shikijs/transformers` | 4.2.0 | teisendajate võrdsustestid |

Shiki ise on võrdlusalus. Taandustestide komplektis on **214 stsenaariumi**, igaüks ühe keele ja ühe teema näidis vaikevalikutega. Iga stsenaariumi tõstavad esile nii Shiki kui ka shikiphp ning mõlema HTML string peab olema identne pärast algus- ja lõputühikute eemaldamist. Kokku katavad stsenaariumid 167 paketiga kaasas olevast 253 grammatikast, `lang: 'ansi'` ja kõik 65 teemat. Valikuid (`structure`, `tabindex`, `colorReplacements`, kaks teemat, `defaultColor` ja muud), `codeToTokensWithThemes` ning sisseehitatud teisendajaid kontrollitakse eraldi võrdsustestidega, mille oodatav väljund jäädvustati samadest Shiki versioonidest.

Sellest tuleneb kaks piirangut. Shiki vaikemootor on WebAssemblyks kompileeritud Oniguruma, võrdlusalus kasutab aga teegi Shiki JavaScript regulaaravaldiste mootorit — sama mootorit, millele shikiphp on port. Hilisemaid Shiki väljalaskeid (4.x haru) pole kontrollitud.

## Kuidas see töötab

shikiphp põhineb tarnitaval puhtal PHP **JavaScript regulaaravaldiste mootoril** allikast
[`inline0/phasis`](https://github.com/inline0/phasis), mida toidab PHP port allikast
[`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Shiki
JavaScript regulaaravaldiste mootor teisendab TextMate grammatikates olevad Oniguruma mustrid
JavaScript `RegExp`-ks, seega on JS regulaaravaldiste mootor loomulik alus — see võimaldab
shikiphp-l vasteid mootori väljundiga nihke kaupa võrrelda.

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

Täielikku töövoogu kirjeldab [arhitektuur](https://shikiphp.inline0.dev/et/docs/architecture).

## Nõuded

- PHP 8.2 või uuem (CI käivitab testikomplekti versiooniga PHP 8.4)
- `ext-json` ja `ext-mbstring` (mõlemad on kaasas peaaegu iga PHP järguga)

## Kuhu edasi

- [Alustamine](https://shikiphp.inline0.dev/et/docs/getting-started) — paigalda ja renderda oma esimene plokk.
- [API](https://shikiphp.inline0.dev/et/docs/api) — kõik saadaolevad meetodid.
- [Valikud](https://shikiphp.inline0.dev/et/docs/options) — kõik valikud, mida `codeToHtml` aktsepteerib.
- [Teisendajad](https://shikiphp.inline0.dev/et/docs/transformers) — konksude töövoog ja sisseehitatud teisendajad.
- [CLI](https://shikiphp.inline0.dev/et/docs/cli) — `bin/shikiphp highlight`, `langs` ja `themes`.

## Litsents

MIT, autoriõigus inline0. Kaasasolevate TextMate grammatikate ja teemade litsentsid jäävad samaks, mis nende algsetel versioonidel.