# shikiphp

shikiphp منفذ خالص بـPHP لـ [Shiki](https://shiki.style)، أداة تمييز البنية اللغوية التي تلوّن الكود باستخدام قواعد TextMate والسمات نفسها في VS Code. ويقسّم الكود إلى رموز باستخدام **قواعد TextMate** نفسها، ثم يلوّنه باستخدام **سمات VS Code** نفسها التي يستخدمها Shiki، لينتج HTML مماثلًا لـ Shiki 3.23.0 — بالكامل ضمن PHP.

لا حاجة إلى بيئة تشغيل Node. ولا إلى إضافات PHP تتجاوز `json` و`mbstring`. ولا ربط أصلي بـ Oniguruma. ولا تشغيل عملية JavaScript خارجيًا، ولا API مستضاف.

```php
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`](https://github.com/microsoft/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` | 3.23.0 | المرجع، ويعمل بمحرك التعبيرات النمطية JavaScript الخاص به |
| `tm-grammars` | 1.31.15 | القواعد المضمّنة |
| `tm-themes` | 1.12.2 | السمات المضمّنة |
| `@shikijs/transformers` | 4.2.0 | اختبارات تكافؤ المحولات |

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`](https://github.com/inline0/phasis)، ويستخدم منفذًا بـPHP لـ [`oniguruma-to-es`](https://github.com/slevithan/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)
```

راجع [البنية](https://shikiphp.inline0.dev/ar/docs/architecture) للاطلاع على المسار كاملًا.

## المتطلبات

- PHP 8.2 أو أحدث (تشغّل CI مجموعة الاختبارات على PHP 8.4)
- `ext-json` و`ext-mbstring` (مضمّنان في جميع إصدارات PHP تقريبًا)

## الخطوة التالية

- [البدء](https://shikiphp.inline0.dev/ar/docs/getting-started) — التثبيت وعرض كتلتك الأولى.
- [API](https://shikiphp.inline0.dev/ar/docs/api) — جميع الطرق المتاحة.
- [الخيارات](https://shikiphp.inline0.dev/ar/docs/options) — كل الخيارات التي يقبلها `codeToHtml`.
- [المحولات](https://shikiphp.inline0.dev/ar/docs/transformers) — مسار الخطافات والمحولات المضمّنة.
- [CLI](https://shikiphp.inline0.dev/ar/docs/cli) — `bin/shikiphp highlight` و`langs` و`themes`.

## الترخيص

MIT، حقوق النشر لـ inline0. تحتفظ قواعد TextMate والسمات المضمّنة بتراخيصها الأصلية.