# Benutzerdefinierte Sprachen und Themes

Das mitgelieferte Set umfasst den vollständigen Shiki-Katalog. Du kannst aber auch eigene TextMate-Grammatiken oder VS Code-Themes aus decodiertem JSON registrieren. Beides wird in der Instanz `Highlighter` gespeichert.

## Benutzerdefinierte Themes

Decodiere eine VS Code-Theme-Datei JSON und übergib sie an `loadTheme`. Das Theme wird über seine `name` identifiziert. Ein benutzerdefiniertes Theme ersetzt ein mitgeliefertes Theme mit demselben Namen.

```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
]);
```

## Benutzerdefinierte Grammatiken

`loadGrammar` registriert eine decodierte `.tmLanguage.json`, sodass jeder Einstiegspunkt sie anhand der Sprach-ID verwenden kann:

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

- `$langId` — die ID, über die du darauf verweist. Falls nicht angegeben, wird zuerst die `name` der Grammatik verwendet, dann ihre `scopeName`.
- `$aliases` — zusätzliche IDs, die auf dieselbe Grammatik verweisen.
- `$embedded` — Sprach-IDs, die diese Grammatik einbettet, damit auch deren Grammatiken aufgelöst werden.

```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',
]);
```

Grammatikreferenzen `include` (`#repo`, `$self`, `$base`, `other.scope`) und eingebettete Sprachen werden anhand der bereits beim Highlighter registrierten Grammatiken aufgelöst. Registriere daher zuerst alle Abhängigkeiten.

## Einen benutzerdefinierten Highlighter über die Fassade verwenden

Wenn die statische Fassade `Shikiphp` deinen angepassten Highlighter verwenden soll, übergib ihn mit `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']]);
```

Rufe `Shikiphp::reset()` auf, um wieder zum standardmäßigen mitgelieferten Highlighter zu wechseln.