# Първи стъпки

## Инсталиране

```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/bg/docs/options#defaultcolor) или да зададете `defaultColor: false`,
за да се генерират само променливи.

## Идентификатори на езици и псевдоними

Езиците се посочват чрез идентификатора или псевдонима си Shiki — `php`, `ts`, `js`,
`rust`, `python`, `html` и т.н. Вижте [Езици](https://shikiphp.inline0.dev/bg/docs/languages), за да научите
как да изведете всичко включено, и [Теми](https://shikiphp.inline0.dev/bg/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/bg/docs/api) за пълния набор от възможности.