shikiphp

shikiphp to port Shiki 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.

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), 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.

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, zasilanym przez port PHP 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.

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 — instalacja i renderowanie pierwszego bloku.
• API — pełny zestaw metod.
• Opcje — wszystkie opcje obsługiwane przez codeToHtml.
• Transformery — potok hooków i wbudowane elementy.
• CLI — bin/shikiphp highlight, langs i themes.

Licencja

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