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 وفق أولوية محددات النطاق ومطابقة النطاقات الأصلية
• HTML متوافق مع Shiki: سمتان فاتحة وداكنة عبر متغيرات 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 على محرك تعبيرات نمطية JavaScript خالص بـPHP ومضمّن ضمن المشروع، من inline0/phasis، ويستخدم منفذًا بـPHP لـ oniguruma-to-es. يحوّل محرك التعبيرات النمطية JavaScript الخاص بـ Shiki أنماط 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 والسمات المضمّنة بتراخيصها الأصلية.