# shikiphp

shikiphp on puhdas-PHP-porttaus lähteestä [Shiki](https://shiki.style), syntaksikorostimesta, joka värittää koodin samoilla TextMate-kieliopilla ja teemoilla kuin VS Code. Se pilkkoo koodin samoilla **TextMate-kieliopilla** ja värittää sen samoilla **VS Code-teemoilla**, joita Shiki käyttää, tuottaen saman HTMLn kuin Shiki 3.23.0 — kokonaan ympäristössä PHP.

Ei Node-ympäristöä. Ei muita `json`-laajennuksia kuin PHP ja `mbstring`. Ei natiivia Oniguruma-sidosta. Ei ulkoisen JavaScript-prosessin käynnistämistä eikä isännöityä API-palvelua.

```php
use Shikiphp\Shikiphp;

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

## Miksi shikiphp

Palvelimella renderöity syntaksikorostus ympäristössä PHP tarkoittaa yleensä jotakin kolmesta kompromissista: Node-prosessin käynnistämistä, isännöidyn API-palvelun kutsumista tai tyytymistä säännöllisiin lausekkeisiin perustuvaan korostimeen, joka ei oikeasti ymmärrä kieltä. Mikään näistä ei sovi hyvin ympäristöön Laravel, WordPress tai staattisen sivuston koontivaiheeseen.

shikiphp poistaa kompromissin porttaamalla lähteen Shiki todellisen käsittelyketjun ympäristöön PHP:

- TextMate-kieliopin jäsennin (uskollinen porttaus lähteestä [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), joka tukee upotettuja kieliä, injektioita ja sisäkkäisiä repositorioita
- VS Code-teemojen selvitys laajuusvalitsimen tarkkuuden ja ylälaajuuden täsmäytyksen perusteella
- Shiki-yhteensopiva HTML: vaaleat ja tummat teemat CSS-muuttujilla, `codeToHast`, muuntimet (kaikki koukut), koristeet, `colorReplacements`, `structure: 'inline'` ja ANSI-korostus (`lang: 'ansi'`)
- **koko Shiki-paketti** — kaikki `tm-grammars` kielet (235 sekä 18 niiden upottamaa apukielioppia) ja kaikki `tm-themes` teemaa (65)

## Vastaavuus lähteen Shiki 3.23.0 kanssa

Tuloste ei ole vain ”riittävän lähellä”, vaan se tarkistetaan lukittua Shiki-julkaisua vasten.

| Paketti | Versio | Käyttötarkoitus |
| --- | --- | --- |
| `shiki` | 3.23.0 | vertailukohta, suoritetaan sen JavaScript-säännöllisten lausekkeiden moottorilla |
| `tm-grammars` | 1.31.15 | mukana toimitetut kieliopit |
| `tm-themes` | 1.12.2 | mukana toimitetut teemat |
| `@shikijs/transformers` | 4.2.0 | muuntimien vastaavuustestit |

Shiki itse toimii vertailukohtana. Regressiotestien aineistossa on **214 skenaariota**. Kukin niistä on yhdellä kielellä ja yhdellä teemalla korostettu näyte oletusasetuksilla. Sekä Shiki että shikiphp korostavat jokaisen skenaarion, ja tuloksena syntyvien HTML-merkkijonojen on oltava samat, kun alun ja lopun tyhjemerkit on poistettu. Skenaariot kattavat yhdessä 167 253-paketin kieliopista, `lang: 'ansi'` ja kaikki 65 teemaa. Asetukset (`structure`, `tabindex`, `colorReplacements`, kahden teeman tila, `defaultColor` ja muut), `codeToTokensWithThemes` sekä sisäänrakennetut muuntimet käydään läpi erillisissä vastaavuustesteissä, joiden odotetut tulosteet tallennettiin samoista Shiki-versioista.

Tästä seuraa kaksi rajoitusta. Shikin oletusmoottori on Oniguruma, joka on käännetty WebAssemblyksi. Vertailukohta käyttää sen sijaan Shikin JavaScript-säännöllisten lausekkeiden moottoria, jota shikiphp porttaa. Myöskään myöhempiä Shiki-julkaisuja (4.x-sarjaa) ei ole tarkistettu.

## Näin se toimii

shikiphp perustuu vendoroituun, puhtaasti PHP-kielellä toteutettuun **JavaScript-regex-moottoriin**, joka on peräisin lähteestä [`inline0/phasis`](https://github.com/inline0/phasis) ja käyttää syötteenä PHP-porttausta lähteestä [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Shiki:n JavaScript-regex-moottori muuntaa TextMate-kielioppien Oniguruma-mallit JavaScript `RegExp`-muotoon, joten JS-regex-moottori on luonteva perusta: sen avulla shikiphp voi täsmätä moottorin tulokseen tavu tavulta.

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

Katso koko käsittelyketju kohdasta [Arkkitehtuuri](https://shikiphp.inline0.dev/fi/docs/architecture).

## Vaatimukset

- PHP 8.2 tai uudempi (CI suorittaa testisarjan versiolla PHP 8.4)
- `ext-json` ja `ext-mbstring` (sisältyvät lähes kaikkiin PHP-koontiversioihin)

## Seuraavaksi

- [Aloitus](https://shikiphp.inline0.dev/fi/docs/getting-started) — asenna työkalu ja luo ensimmäinen lohkosi.
- [API](https://shikiphp.inline0.dev/fi/docs/api) — kaikki käytettävissä olevat metodit.
- [Valinnat](https://shikiphp.inline0.dev/fi/docs/options) — kaikki asetukset, jotka `codeToHtml` hyväksyy.
- [Muuntimet](https://shikiphp.inline0.dev/fi/docs/transformers) — koukkukäsittelyketju ja sisäänrakennetut muuntimet.
- [CLI](https://shikiphp.inline0.dev/fi/docs/cli) — `bin/shikiphp highlight`, `langs` ja `themes`.

## Lisenssi

MIT, tekijänoikeudet inline0. Mukana toimitettujen TextMate-kielioppien ja teemojen alkuperäiset lisenssit säilyvät voimassa.