# البدء

## التثبيت

```bash
composer require shikiphp/shikiphp
```

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

## كتلتك الأولى

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

```php
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)، لتتكيف الكتلة المعروضة الواحدة مع الوضعين الفاتح والداكن:

```php
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:

```css
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`](https://shikiphp.inline0.dev/ar/docs/options#defaultcolor)، أو ضبط `defaultColor: false` لإصدار المتغيرات وحدها.

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

تُشار إلى اللغات بمعرّف Shiki أو بأحد أسمائها البديلة — `php`، و`ts`، و`js`، و`rust`، و`python`، و`html`، وهكذا. راجع [اللغات](https://shikiphp.inline0.dev/ar/docs/languages) لمعرفة كيفية عرض كل ما تتضمنه الحزمة، و[السمات](https://shikiphp.inline0.dev/ar/docs/themes) لمعرّفات السمات.

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

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

```php
use Shikiphp\Shikiphp;

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

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

راجع [API](https://shikiphp.inline0.dev/ar/docs/api) للاطلاع على الواجهة كاملة.