Zum Inhalt springen

API

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu 22946a5

shikiphp bietet zwei Einstiegspunkte: die statische Fassade Shikiphp für häufige Anwendungsfälle und die Instanz Highlighter für alles Weitere (HAST-Ausgabe, benutzerdefinierte Grammatiken und Themes, Theme-Varianten und Bundle-Introspektion).

Die Fassade Shikiphp

Shikiphp\Shikiphp ist eine schlanke statische Fassade über einem verzögert erstellten, zwischengespeicherten, gebündelten Highlighter.

Shikiphp::codeToHtml

PHP
public static function codeToHtml(string $code, array $options): string

Tokenisiert $code und rendert einen vollständigen <pre class="shiki …">-HTML-Block. Das Optionsarray enthält immer ein lang sowie entweder ein theme oder eine Zuordnung themes und beliebige Darstellungsoptionen.

PHP
use Shikiphp\Shikiphp;

echo Shikiphp::codeToHtml($code, ['lang' => 'php', 'theme' => 'github-dark']);

Shikiphp::codeToTokens

PHP
/** @return list<list<ThemedToken>> */
public static function codeToTokens(string $code, array $options): array

Gibt statt HTML das unverzierte 2D-Tokenraster (eine innere Liste pro Zeile) aus Shikiphp\Render\ThemedToken-Objekten zurück.

PHP
use Shikiphp\Shikiphp;

$lines = Shikiphp::codeToTokens($code, ['lang' => 'js', 'theme' => 'nord']);

foreach ($lines as $line) {
    foreach ($line as $token) {
        // $token->content, $token->color, $token->fontStyle,
        // $token->bgColor, $token->htmlStyle, $token->offset
    }
}

Shikiphp::codeToTokensBase

PHP
/** @return list<list<ThemedToken>> */
public static function codeToTokensBase(string $code, array $options): array

Ein Alias von codeToTokens, dessen Name Shikis codeToTokensBase entspricht.

Shikiphp::codeToTokensResult

PHP
public static function codeToTokensResult(string $code, array $options): TokensResult

Gibt das umfangreiche Ergebnis zurück, das Shikis oberstes codeToTokens nachbildet: das Tokenraster sowie die aufgelösten Farben, den Theme-Namen, den Root-Stil für duale Themes und den finalen Grammatikzustand. Siehe unten TokensResult.

PHP
use Shikiphp\Shikiphp;

$result = Shikiphp::codeToTokensResult($code, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);

$result->tokens;       // list<list<ThemedToken>>
$result->fg;           // "#e1e4e8"
$result->bg;           // "#24292e"
$result->themeName;    // "github-dark"
$result->grammarState; // GrammarState

Shikiphp::getLastGrammarState

PHP
public static function getLastGrammarState(string $code, array $options): GrammarState

Tokenisiert $code und gibt den am Ende erreichten Grammatikzustand zurück (Shikis getLastGrammarState). Übergib ihn über die Option grammarState zurück, um ein späteres Fragment aus demselben Zustand weiter zu tokenisieren – nützlich für inkrementelle Hervorhebung. Löst einen Fehler aus, wenn lang den Wert 'ansi' hat (ANSI besitzt keinen Grammatikzustand).

PHP
use Shikiphp\Shikiphp;

$state = Shikiphp::getLastGrammarState("/* unterminated comment", [
    'lang'  => 'js',
    'theme' => 'nord',
]);

$html = Shikiphp::codeToHtml("still inside the comment */", [
    'lang'         => 'js',
    'theme'        => 'nord',
    'grammarState' => $state,
]);

Shikiphp::highlighter

PHP
public static function highlighter(): Highlighter

Gibt den gemeinsam genutzten, gebündelten Highlighter zurück und erstellt ihn bei der ersten Verwendung. Damit kannst du auf die unten aufgeführten Instanzmethoden zugreifen.

Shikiphp::use und Shikiphp::reset

PHP
public static function use(Highlighter $highlighter): void
public static function reset(): void

use setzt einen benutzerdefinierten Highlighter ein (zum Beispiel einen, in den du eigene Grammatiken oder Themes geladen hast), sodass die Fassade ihn verwendet. reset löscht die zwischengespeicherte Instanz, damit beim nächsten Aufruf der standardmäßige gebündelte Highlighter neu erstellt wird.

Das Highlighter

Shikiphp\Highlighter bietet den vollen Funktionsumfang. Rufe die gemeinsam genutzte gebündelte Instanz mit Shikiphp::highlighter() ab oder erstelle explizit eine eigene:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Es implementiert codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult und getLastGrammarState mit denselben Signaturen wie die Fassade sowie die folgenden Funktionen.

Highlighter::codeToHast

PHP
public function codeToHast(string $code, array $options): \Shikiphp\Hast\Element

Erstellt den pre.shiki > code > (span.line > span)*-HAST-Baum, den Shiki erstellt, sodass du ihn selbst durchlaufen, ändern oder serialisieren kannst. Diesen serialisiert codeToHtml intern.

PHP
use Shikiphp\Shikiphp;

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

Highlighter::codeToTokensWithThemes

PHP
/** @return list<list<ThemedTokenWithVariants>> */
public function codeToTokensWithThemes(string $code, array $options): array

Tokenisiert einmal pro Theme und führt das Ergebnis in einem variants pro Token zusammen, das über den Theme-Schlüssel indexiert ist. Dies bildet Shikis codeToTokensWithThemes nach. Erfordert eine Zuordnung themes.

PHP
use Shikiphp\Shikiphp;

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

$lines[0][0]->content;            // token text
$lines[0][0]->variants['light'];  // ThemedTokenStyle for the light theme
$lines[0][0]->variants['dark'];   // ThemedTokenStyle for the dark theme

Highlighter::loadGrammar und Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Registriere eine benutzerdefinierte TextMate-Grammatik oder ein VS Code-Theme aus dekodiertem JSON. Siehe Benutzerdefinierte Sprachen und Themes.

Bundle-Introspektion

PHP
/** @return list<string> */ public function loadedLanguages(): array
/** @return list<string> */ public function loadedThemes(): array
/** @return list<string> */ public function bundledLanguages(): array
/** @return list<string> */ public function bundledThemes(): array

loadedLanguages/loadedThemes melden alle derzeit nutzbaren IDs (gebündelte sowie registrierte benutzerdefinierte). bundledLanguages/bundledThemes melden nur die mitgelieferten IDs. Siehe Sprachen und Themes.

Wertobjekte

ThemedToken

Shikiphp\Render\ThemedToken ist ein formatierter Textabschnitt:

PHP
final class ThemedToken
{
    public readonly string $content;
    public readonly ?string $color;
    public readonly int $fontStyle;      // FontStyle bitmask
    public readonly ?string $bgColor;
    public readonly ?string $htmlStyle;  // pre-built inline style (dual themes / ANSI)
    public readonly int $offset;         // UTF-16 code-unit offset into the source
}

fontStyle ist eine Bitmaske aus Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult ist der Rückgabewert von codeToTokensResult:

PHP
final class TokensResult
{
    public readonly array $tokens;             // list<list<ThemedToken>>
    public readonly ?string $fg;               // resolved foreground
    public readonly ?string $bg;               // resolved background
    public readonly ?string $themeName;        // single id, or "shiki-themes …"
    public readonly string|false|null $rootStyle; // dual-theme root style (or null)
    public readonly ?GrammarState $grammarState;
}

GrammarState

Shikiphp\GrammarState enthält den Regelstapel des Tokenizers (nach Theme-Namen indiziert), damit die Hervorhebung an einem Zwischenpunkt fortgesetzt werden kann.

PHP
final class GrammarState
{
    public readonly string $lang;

    public function theme(): string;          // first theme name
    public function themes(): array;          // list<string>
    public function getScopes(?string $theme = null): array; // scopes in effect, innermost first
    public function withTheme(string $theme): self;
}