# shikiphp

shikiphp to port [Shiki](https://shiki.style) napisany wyłącznie w PHP. Ten mechanizm podświetlania składni koloruje kod za pomocą tych samych gramatyk TextMate i motywów co VS Code. Tokenizuje kod przy użyciu tych samych **gramatyk TextMate** i koloruje go według tych samych **motywów VS Code**, których używa Shiki, generując taki sam wynik HTML jak Shiki 3.23.0 — w całości w PHP.

Bez środowiska uruchomieniowego Node. Bez rozszerzeń PHP poza `json` i `mbstring`. Bez natywnego
powiązania Oniguruma. Bez uruchamiania procesu JavaScript i bez hostowanego API.

```php
use Shikiphp\Shikiphp;

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

## Dlaczego shikiphp

Podświetlanie składni renderowane po stronie serwera w PHP zwykle wiąże się z jednym z trzech
kompromisów: uruchomieniem Node, wywołaniem hostowanego API lub użyciem podświetlania opartego na wyrażeniach regularnych, które nie rozumie języka. Żadne z tych rozwiązań nie pasuje dobrze do Laravel, WordPress ani etapu kompilacji witryny statycznej.

shikiphp eliminuje ten kompromis, przenosząc rzeczywisty potok Shiki do PHP:

- Tokenizator gramatyk TextMate (wierny port
  [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), obejmujący
  osadzone języki, wstrzyknięcia i zagnieżdżone repozytoria
- Rozpoznawanie motywów VS Code z uwzględnieniem szczegółowości selektora zakresu i dopasowania zakresu nadrzędnego
- HTML zgodne z Shiki: jasne i ciemne motywy przez zmienne CSS, `codeToHast`,
  transformatory (każdy punkt rozszerzeń), dekoracje, `colorReplacements`,
  `structure: 'inline'` i podświetlanie ANSI (`lang: 'ansi'`)
- **Pełny pakiet Shiki** — każdy język `tm-grammars` (235 oraz 18
  gramatyk pomocniczych, które osadzają) i każdy motyw `tm-themes` (65)

## Zgodność z Shiki 3.23.0

Wynik nie jest „wystarczająco zbliżony”: jest sprawdzany względem przypiętej wersji Shiki.

| Pakiet | Wersja | Zastosowanie |
| --- | --- | --- |
| `shiki` | 3.23.0 | wzorzec odniesienia, uruchamiany z silnikiem regex JavaScript |
| `tm-grammars` | 1.31.15 | dołączone gramatyki |
| `tm-themes` | 1.12.2 | dołączone motywy |
| `@shikijs/transformers` | 4.2.0 | testy zgodności transformerów |

Samo Shiki jest wzorcem odniesienia. Zestaw testów regresyjnych obejmuje **214 scenariuszy**,
z których każdy jest próbką w jednym języku i jednym motywie przy domyślnych opcjach. Każdy
scenariusz jest podświetlany przez Shiki i shikiphp, a oba ciągi HTML muszą
być identyczne po usunięciu białych znaków z początku i końca. Łącznie
scenariusze obejmują 167 spośród 253 dołączonych gramatyk, `lang: 'ansi'` oraz wszystkie 65
motywów. Opcje (`structure`, `tabindex`, `colorReplacements`, dwa motywy,
`defaultColor` i pozostałe), `codeToTokensWithThemes` oraz wbudowane
transformatory są objęte osobnymi testami zgodności, których oczekiwane wyniki
zapisano z tych samych wersji Shiki.

Wynikają z tego dwa ograniczenia. Domyślny silnik Shiki to Oniguruma skompilowany do WebAssembly, a wzorzec odniesienia używa zamiast niego silnika regex JavaScript należącego do Shiki — tego samego, który przenosi shikiphp. Nie sprawdzono też późniejszych wydań Shiki z linii 4.x.

## Jak to działa

shikiphp opiera się na dołączonym silniku regex pure-PHP **JavaScript** z
[`inline0/phasis`](https://github.com/inline0/phasis), zasilanym przez port PHP
[`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Silnik regex Shiki
JavaScript konwertuje wzorce Oniguruma w gramatykach TextMate na
JavaScript `RegExp`, dlatego silnik regex JS jest naturalną podstawą — pozwala
shikiphp dopasować wynik tego silnika z dokładnością do każdej pozycji.

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

Pełny przepływ opisano w sekcji [Architektura](https://shikiphp.inline0.dev/pl/docs/architecture).

## Wymagania

- PHP 8.2 lub nowszy (CI uruchamia zestaw testów na PHP 8.4)
- `ext-json` i `ext-mbstring` (są dołączane do niemal każdej kompilacji PHP)

## Co dalej

- [Pierwsze kroki](https://shikiphp.inline0.dev/pl/docs/getting-started) — instalacja i renderowanie pierwszego bloku.
- [API](https://shikiphp.inline0.dev/pl/docs/api) — pełny zestaw metod.
- [Opcje](https://shikiphp.inline0.dev/pl/docs/options) — wszystkie opcje obsługiwane przez `codeToHtml`.
- [Transformery](https://shikiphp.inline0.dev/pl/docs/transformers) — potok hooków i wbudowane elementy.
- [CLI](https://shikiphp.inline0.dev/pl/docs/cli) — `bin/shikiphp highlight`, `langs` i `themes`.

## Licencja

MIT, prawa autorskie inline0. Dołączone gramatyki i motywy TextMate zachowują
licencje źródłowe.