# shikiphp

shikiphp este un port pur-PHP al [Shiki](https://shiki.style), evidențiatorul de sintaxă ce colorează codul cu aceleași gramatici TextMate și teme ca VS Code. Tokenizează codul cu aceleași **gramatici TextMate** și îl colorează cu aceleași **teme VS Code** folosite de Shiki, generând același HTML ca Shiki 3.23.0 — totul în PHP.

Fără runtime Node. Fără extensii PHP în afara `json` și `mbstring`. Fără legături native Oniguruma. Fără lansarea unui proces JavaScript și fără API găzduit.

```php
use Shikiphp\Shikiphp;

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

## De ce shikiphp

Evidențierea sintaxei pe server în PHP presupune de obicei unul dintre trei compromisuri: pornirea Node într-un proces extern, apelarea unui API găzduit sau folosirea unui evidențiator bazat pe regex, care nu înțelege cu adevărat limbajul. Niciuna dintre aceste variante nu se integrează firesc într-o etapă de construire pentru Laravel, WordPress sau site-uri statice.

shikiphp elimină compromisul portând procesul real al Shiki în PHP:

- un tokenizer de gramatică TextMate (port fidel al [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), cu limbi încorporate, injecții și depozite imbricate
- rezolvarea temelor VS Code, cu specificitatea selectorilor de domeniu și potrivirea domeniilor părinte
- Shiki-compatibil HTML: teme duale deschise/întunecate prin variabile CSS, `codeToHast`, transformatoare (toate hook-urile), decorațiuni, `colorReplacements`, `structure: 'inline'` și evidențiere ANSI (`lang: 'ansi'`)
- **întregul pachet Shiki** — toate limbile `tm-grammars` (235 și cele 18 gramatici auxiliare încorporate) și toate temele `tm-themes` (65)

## Comparat cu Shiki 3.23.0

Rezultatul nu este doar „destul de apropiat”: este verificat față de o versiune Shiki fixată.

| Pachet | Versiune | Utilizare |
| --- | --- | --- |
| `shiki` | 3.23.0 | etalonul, rulat cu motorul regex JavaScript |
| `tm-grammars` | 1.31.15 | gramaticile incluse |
| `tm-themes` | 1.12.2 | temele incluse |
| `@shikijs/transformers` | 4.2.0 | testele de paritate pentru transformatoare |

Shiki este chiar etalonul. Suita de regresie conține **214 de scenarii**, fiecare fiind un exemplu într-o limbă și o temă, cu opțiunile implicite. Fiecare scenariu este evidențiat de Shiki și shikiphp, iar cele două șiruri HTML trebuie să fie identice după eliminarea spațiilor albe de la început și sfârșit. Împreună, scenariile acoperă 167 dintre cele 253 de gramatici incluse, `lang: 'ansi'` și toate cele 65 de teme. Opțiunile (`structure`, `tabindex`, `colorReplacements`, temele duale, `defaultColor` și restul), `codeToTokensWithThemes` și transformatoarele încorporate sunt acoperite de teste de paritate separate, ale căror rezultate așteptate au fost capturate folosind aceleași versiuni Shiki.

Rezultă două limite. Motorul implicit al Shiki este Oniguruma compilat în WebAssembly, iar etalonul folosește în schimb motorul regex JavaScript al Shiki, motorul pe care îl portează shikiphp. În plus, versiunile Shiki ulterioare (seria 4.x) nu au fost verificate.

## Cum funcționează

shikiphp se bazează pe un PHP **motor regex JavaScript pur** inclus direct din [implementarea`inline0/phasis`](https://github.com/inline0/phasis), alimentat de un port PHP al [implementării`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Motorul regex Shiki convertește modelele JavaScript din gramaticile Oniguruma în TextMateJavaScript `RegExp`, așa că un motor regex JS este baza firească — îi permite lui shikiphp să se potrivească cu rezultatul motorului, poziție cu poziție.

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

Consultați [Arhitectura](https://shikiphp.inline0.dev/ro/docs/architecture) pentru întregul flux de procesare.

## Cerințe

- PHP 8.2 sau o versiune ulterioară (CI rulează suita de teste pe PHP 8.4)
- `ext-json` și `ext-mbstring` (ambele sunt incluse în aproape fiecare compilare PHP)

## Ce urmează

- [Noțiuni introductive](https://shikiphp.inline0.dev/ro/docs/getting-started) — instalați și redați primul bloc.
- [API](https://shikiphp.inline0.dev/ro/docs/api) — toate metodele disponibile.
- [Opțiuni](https://shikiphp.inline0.dev/ro/docs/options) — toate opțiunile acceptate de `codeToHtml`.
- [Transformatoare](https://shikiphp.inline0.dev/ro/docs/transformers) — fluxul de hook-uri și cele incluse.
- [CLI](https://shikiphp.inline0.dev/ro/docs/cli) — `bin/shikiphp highlight`, `langs` și `themes`.

## Licență

MIT, drepturi de autor inline0. Gramaticile și temele incluse TextMate păstrează
licențele din proiectele-sursă.