shikiphp

shikiphp е изцяло-PHP порт на Shiki — осветител на синтаксиса, който оцветява кода със същите граматики и теми TextMate като VS Code. Той токенизира кода със същите граматики TextMate и го оцветява със същите теми VS Code, използвани от Shiki, като генерира същия HTML като Shiki 3.23.0 — изцяло на PHP.

Без среда за изпълнение на Node. Без разширения PHP извън json и mbstring. Без нативна обвързка Oniguruma. Без стартиране на отделен процес JavaScript и без хостван API.

use Shikiphp\Shikiphp;

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

Защо shikiphp

Осветяването на синтаксис от страна на сървъра в PHP обикновено изисква един от три компромиса: стартиране на Node, извикване на хостван API или използване на осветител, базиран на регулярни изрази, който всъщност не разбира езика. Нито един от тези варианти не се вписва добре в Laravel, WordPress или стъпка за компилация на статичен сайт.

shikiphp премахва компромиса, като пренася реалния конвейер на Shiki към PHP:

• токенизатор на граматики TextMate (точен порт на vscode-textmate), включително вградени езици, инжекции и вложени хранилища
• разрешаване на теми VS Code със специфичност на селекторите за обхват и съпоставяне на родителски обхвати
• Shiki-съвместим HTML: двойни светли/тъмни теми чрез променливи CSS, codeToHast, трансформатори (всички куки), декорации, colorReplacements, structure: 'inline' и осветяване ANSI (lang: 'ansi')
• пълният пакет Shiki — всеки език tm-grammars (235, плюс 18 помощни граматики, които се вграждат) и всяка тема tm-themes (65)

Съпоставка с Shiki 3.23.0

Изходът не е „достатъчно близък“: проверява се спрямо фиксирана версия на Shiki.

Самият Shiki е еталонът. Комплектът за регресионни проверки съдържа 214 сценария, всеки от които е пример на един език и с една тема и настройки по подразбиране. Всеки сценарий се осветява от Shiki и shikiphp, а двата низа HTML трябва да са идентични след премахване на водещите и крайните интервали. Заедно сценариите обхващат 167 от 253 вградените граматики, lang: 'ansi' и всичките 65 теми. Опциите (structure, tabindex, colorReplacements, двойни теми, defaultColor и останалите), codeToTokensWithThemes и вградените трансформатори се проверяват с отделни тестове за съответствие, чиито очаквани изходи са заснети от същите версии Shiki.

Оттук следват две ограничения. Механизмът по подразбиране на Shiki е Oniguruma, компилиран до WebAssembly, а еталонът използва вместо това регулярния механизъм JavaScript на Shiki — механизмът, който използва портът на shikiphp. Освен това по-новите версии на Shiki (серията 4.x) не са проверявани.

Как работи

shikiphp е изградена върху вграден енджин за регулярни изрази с чист PHP JavaScript от inline0/phasis, захранван от PHP порт на oniguruma-to-es. Енджинът за регулярни изрази на Shiki JavaScript преобразува шаблоните на Oniguruma в граматиките на TextMate до JavaScript RegExp, така че енджинът за регулярни изрази на JS е естествената основа — позволява на shikiphp да съпоставя изхода на този енджин отместване по отместване.

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

Вижте Архитектура за пълния конвейер.

Изисквания

• PHP 8.2 или по-нова версия (CI изпълнява тестовия пакет с PHP 8.4)
• ext-json и ext-mbstring (и двете са включени в почти всяка компилация на PHP)

Какво следва

• Първи стъпки — инсталирайте и генерирайте първия си блок.
• API — пълният набор от методи.
• Опции — всички опции, които приема codeToHtml.
• Трансформатори — конвейерът с куки и вградените трансформатори.
• CLI — bin/shikiphp highlight, langs и themes.

Лиценз

MIT, авторско право на inline0. Вградените граматики и теми TextMate запазват лицензите си от първоначалните си проекти.