# Потребителски езици и теми

Вграденият набор включва целия каталог Shiki, но можете да регистрирате своя
граматика TextMate или тема VS Code от декодиран JSON. И двете се съхраняват в
екземпляра `Highlighter`.

## Потребителски теми

Декодирайте файл с тема VS Code JSON и го подайте на `loadTheme`. Темата се идентифицира
по `name`, а потребителска тема замества вградена тема със същото име.

```php
use Shikiphp\Shikiphp;

$highlighter = Shikiphp::highlighter();

$theme = json_decode(file_get_contents('my-theme.json'), true);
$highlighter->loadTheme($theme);

$code = '<?php echo "hello";';

echo $highlighter->codeToHtml($code, [
    'lang'  => 'php',
    'theme' => $theme['name'], // the theme's own name
]);
```

## Потребителски граматики

`loadGrammar` регистрира декодиран `.tmLanguage.json`, така че всяка входна точка може да го използва
чрез идентификатора на езика:

```php
public function loadGrammar(
    array $rawTmLanguage,
    ?string $langId = null,
    array $aliases = [],
    array $embedded = [],
): void
```

- `$langId` — идентификаторът, с който да го посочвате. Ако е пропуснат, се използва `name` на граматиката,
  а след това `scopeName`.
- `$aliases` — допълнителни идентификатори, които сочат към същата граматика.
- `$embedded` — идентификаторите на езиците, които тази граматика вгражда, така че техните граматики също да бъдат намерени.

```php
use Shikiphp\Shikiphp;

$highlighter = Shikiphp::highlighter();

$grammar = json_decode(file_get_contents('mylang.tmLanguage.json'), true);
$highlighter->loadGrammar($grammar, 'mylang', aliases: ['ml']);

$code = file_get_contents('example.mylang');

echo $highlighter->codeToHtml($code, [
    'lang'  => 'mylang',
    'theme' => 'github-dark',
]);
```

Препратките на граматиката `include` (`#repo`, `$self`, `$base`, `other.scope`) и
вградените езици се свързват с граматики, които вече са регистрирани в
осветителя; затова първо регистрирайте всички зависимости.

## Използване на потребителски осветител чрез фасадата

Ако искате статичната фасада `Shikiphp` да използва персонализирания ви осветител,
подайте му го с `Shikiphp::use`:

```php
use Shikiphp\Highlighter;
use Shikiphp\Shikiphp;

$myTheme = json_decode(file_get_contents('my-theme.json'), true);
$myGrammar = json_decode(file_get_contents('mylang.tmLanguage.json'), true);
$code = file_get_contents('example.mylang');

$highlighter = Highlighter::createBundled();
$highlighter->loadTheme($myTheme);
$highlighter->loadGrammar($myGrammar, 'mylang');

Shikiphp::use($highlighter);

// Now the facade delegates to your highlighter.
echo Shikiphp::codeToHtml($code, ['lang' => 'mylang', 'theme' => $myTheme['name']]);
```

Извикайте `Shikiphp::reset()`, за да се върнете към стандартния вграден осветител.