البدء

التثبيت

composer require shikiphp/shikiphp

يتطلب shikiphp PHP 8.2 أو أحدث مع ext-json وext-mbstring — وهما مفعّلان في معظم إصدارات PHP. لا شيء آخر: لا Node، ولا ربطًا أصليًا بـ Oniguruma، ولا إضافات أخرى.

كتلتك الأولى

واجهة Shikiphp الثابتة هي أسرع طريقة للبدء. مرّر إليها الكود ومعرّف اللغة ومعرّف السمة:

use Shikiphp\Shikiphp;

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

echo $html;

يعيد codeToHtml كتلة <pre class="shiki …"> كاملة ذات تنسيق ذاتي. تُكتب ألوان المقدمة والخلفية مباشرةً على <pre>، لذا تُعرض بشكل صحيح دون ورقة أنماط إضافية.

سمتان (فاتحة وداكنة)

بدلًا من theme واحدة، مرّر خريطة themes. يصدر shikiphp متغيرات CSS (مثل Shiki)، لتتكيف الكتلة المعروضة الواحدة مع الوضعين الفاتح والداكن:

use Shikiphp\Shikiphp;

$code = 'const answer: number = 42';

echo Shikiphp::codeToHtml($code, [
    'lang'   => 'ts',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);

افتراضيًا، تُستخدم ألوان سمة light كألوان مضمنة، وتُتاح dark عبر متغيرات --shiki-dark. فعّل السمة الداكنة بقدر بسيط من CSS — المقتطف نفسه الذي توثقه Shiki:

html.dark .shiki,
html.dark .shiki span {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg) !important;
  /* and font styles */
  font-style: var(--shiki-dark-font-style) !important;
  font-weight: var(--shiki-dark-font-weight) !important;
  text-decoration: var(--shiki-dark-text-decoration) !important;
}

يمكنك اختيار السمة التي تكون افتراضية مضمنة عبر الخيار defaultColor، أو ضبط defaultColor: false لإصدار المتغيرات وحدها.

معرّفات اللغات والأسماء البديلة

تُشار إلى اللغات بمعرّف Shiki أو بأحد أسمائها البديلة — php، وts، وjs، وrust، وpython، وhtml، وهكذا. راجع اللغات لمعرفة كيفية عرض كل ما تتضمنه الحزمة، والسمات لمعرّفات السمات.

إعادة استخدام أداة التمييز

تنشئ الواجهة الوسيطة أداة تمييز Highlighter مضمّنة عند الحاجة وتخزّنها مؤقتًا، لذا تعيد الاستدعاءات المتكررة لـ Shikiphp::codeToHtml استخدام ذاكرات القواعد والسمات المؤقتة نفسها. إذا احتجت إلى API الأوسع (مخرجات HAST، والقواعد المخصصة، وشبكات الرموز)، فاحصل على النسخة مباشرةً:

use Shikiphp\Shikiphp;

$code = 'fn main() {}';

$highlighter = Shikiphp::highlighter();
$hast = $highlighter->codeToHast($code, ['lang' => 'rust', 'theme' => 'nord']);

راجع API للاطلاع على الواجهة كاملة.