shikiphp

shikiphp yra grynasis PHP perkėlimas Shiki – sintaksės paryškintuvas, spalvinantis kodą tomis pačiomis TextMate gramatikomis ir temomis kaip VS Code. Jis tokenizuoja kodą tomis pačiomis TextMate gramatikomis ir nuspalvina tomis pačiomis VS Code temomis, kurias naudoja Shiki, todėl sukuriamas toks pat HTML kaip Shiki 3.23.0 – visa tai atliekama PHP.

Nereikia Node aplinkos. Jokių PHP plėtinių, išskyrus json ir mbstring. Nėra savosios Oniguruma sąsajos. Nereikia paleisti atskiro JavaScript proceso ar naudoti talpinamos API.

use Shikiphp\Shikiphp;

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

Kodėl shikiphp

Sintaksės paryškinimas serveryje naudojant PHP paprastai reiškia vieną iš trijų kompromisų: paleisti Node, kreiptis į išorinį API arba tenkintis reguliariosiomis išraiškomis pagrįstu paryškintuvu, kuris iš tikrųjų nesupranta kalbos. Nė vienas iš šių variantų netinka Laravel, WordPress ar statinės svetainės kūrimo etape.

shikiphp panaikina šį kompromisą, perkeldama tikrąjį Shiki procesą į PHP:

• TextMate gramatikos tokenizatorius (tikslus vscode-textmate perkėlimas), apimantis įterptąsias kalbas, injekcijas ir įdėtąsias saugyklas
• VS Code temų parinkimas pagal parinkiklių specifiškumą ir pirminės srities atitikmenis
• su Shiki suderinamas HTML: dvigubos šviesioji ir tamsioji temos per CSS kintamuosius, codeToHast, transformatoriai (visi kabliai), dekoracijos, colorReplacements, structure: 'inline' ir ANSI (lang: 'ansi') paryškinimas
• visas Shiki paketas — visos tm-grammars kalbos (235 ir 18 pagalbinių gramatikų, kurias jos įterpia) ir visos tm-themes temos (65)

Palyginta su Shiki 3.23.0

Rezultatas ne šiaip „pakankamai panašus“: jis tikrinamas pagal fiksuotą Shiki versiją.

Pats Shiki yra etalonas. Regresijų testų rinkinyje yra 214 scenarijų; kiekvienas jų — pavyzdys su viena kalba, viena tema ir numatytosiomis parinktimis. Kiekvieną scenarijų paryškina ir Shiki, ir shikiphp, o abiejų HTML eilutės turi sutapti, pašalinus pradžios ir pabaigos tarpus. Visi šie scenarijai apima 167 iš 253 įtrauktų gramatikų, lang: 'ansi' ir visas 65 temas. Parinktys (structure, tabindex, colorReplacements, dvigubos temos, defaultColor ir kitos), codeToTokensWithThemes bei įtaisytieji transformatoriai tikrinami atskirais atitikties testais; jų laukiamas rezultatas užfiksuotas naudojant tas pačias Shiki versijas.

Iš to kyla du apribojimai. Numatytoji Shiki variklio versija yra Oniguruma, sukompiliuotas į WebAssembly, o etalonas naudoja Shiki JavaScript reguliariųjų išraiškų variklį — tą, kurį perkelia shikiphp. Be to, vėlesnės Shiki versijos (4.x serija) nebuvo tikrintos.

Kaip tai veikia

shikiphp pagrįsta įtrauktu grynai PHP JavaScript reguliariųjų išraiškų varikliu iš inline0/phasis, kuriam naudojamas PHP perkėlimas iš oniguruma-to-es. Shiki JavaScript reguliariųjų išraiškų variklis konvertuoja TextMate gramatikų Oniguruma šablonus į JavaScript RegExp, todėl grynai JS reguliariųjų išraiškų variklis yra natūralus pagrindas — jis leidžia shikiphp tiksliai sutapti su to variklio rezultato poslinkiais.

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

Visą procesą rasite skyriuje Architektūra.

Reikalavimai

• PHP 8.2 ar naujesnė (CI testų rinkinį vykdo su PHP 8.4)
• ext-json ir ext-mbstring (abu pateikiami beveik su kiekvienu PHP rinkiniu)

Kas toliau

• Pradžia — įdiekite ir atvaizduokite savo pirmąjį bloką.
• API — visos metodų galimybės.
• Parinktys — visos codeToHtml priimamos parinktys.
• Transformatoriai — įskiepių procesas ir įtaisytieji transformatoriai.
• CLI — bin/shikiphp highlight, langs ir themes.

Licencija

MIT, autorių teisės priklauso inline0. Įtrauktų TextMate gramatikų ir temų licencijos išlieka tokios, kokias nustatė jų pirminiai autoriai.