Aller au contenu

API

Afficher au format Markdown Modifier sur GitHub Documentation de 22946a5

shikiphp expose deux points d'entrée : la façade statique Shikiphp pour les cas courants, et l'instance Highlighter pour tout le reste (sortie HAST, grammaires et thèmes personnalisés, variantes de thème et inspection du bundle).

La façade Shikiphp

Shikiphp\Shikiphp est une fine façade statique autour d'un highlighter intégré, créé à la demande et mis en cache.

Shikiphp::codeToHtml

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

Analyse $code et génère un bloc complet <pre class="shiki …"> HTML. Le tableau d'options contient toujours un lang, ainsi que soit un theme, soit une correspondance themes, et n'importe laquelle des options de rendu.

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

Renvoie la grille de jetons 2D brute (une liste interne par ligne) d'objets Shikiphp\Render\ThemedToken au lieu de HTML.

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

Un alias de codeToTokens qui reprend le nom codeToTokensBase de Shiki.

Shikiphp::codeToTokensResult

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

Renvoie le résultat détaillé qui reflète le codeToTokens de premier niveau de Shiki : la grille de jetons, les couleurs résolues, le nom du thème, le style racine du thème double et l'état final de la grammaire. Voir TokensResult ci-dessous.

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

Analyse $code et renvoie l'état de grammaire atteint à la fin (getLastGrammarState de Shiki). Transmettez-le via l'option grammarState pour reprendre l'analyse d'un fragment ultérieur à partir du même état — utile pour la mise en évidence incrémentale. Une exception est levée si lang vaut 'ansi' (ANSI n'a pas d'état de grammaire).

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

Renvoie le Highlighter partagé intégré, en le créant lors de sa première utilisation. Utilisez-le pour accéder aux méthodes d’instance ci-dessous.

Shikiphp::use et Shikiphp::reset

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

use remplace le Highlighter intégré par un élément personnalisé (par exemple, un élément auquel vous avez ajouté des grammaires ou des thèmes personnalisés), afin que la façade lui délègue ses opérations. reset efface l'instance mise en cache pour que l'appel suivant recrée le highlighter intégré par défaut.

Le Highlighter

Shikiphp\Highlighter expose toutes les fonctionnalités. Récupérez l'instance intégrée partagée avec Shikiphp::highlighter(), ou créez-en une explicitement :

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Il implémente codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult et getLastGrammarState avec les mêmes signatures que la façade, ainsi que les éléments suivants.

Highlighter::codeToHast

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

Construit l’arbre HAST pre.shiki > code > (span.line > span)* que Shiki construit, prêt à parcourir, modifier ou sérialiser vous-même. C’est ce que codeToHtml sérialise en interne.

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

Tokenise une fois par thème et fusionne le résultat dans variants par jeton, indexés par clé de thème, comme le codeToTokensWithThemes de Shiki. Nécessite une map 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 et Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Enregistrez une grammaire TextMate ou un thème VS Code personnalisé à partir de JSON décodé. Voir Langages et thèmes personnalisés.

Inspection du bundle

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 répertorient tous les identifiants utilisables actuellement (ceux du bundle et ceux que vous avez enregistrés). bundledLanguages/bundledThemes répertorient uniquement les identifiants fournis dans le bundle. Voir Langages et Thèmes.

Objets valeur

ThemedToken

Shikiphp\Render\ThemedToken correspond à une portion de texte mise en forme :

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 est un masque de bits provenant de Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult est la valeur renvoyée par 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 contient la pile de règles du tokenizer (indexée par nom de thème) pour permettre de reprendre la coloration syntaxique depuis un point intermédiaire.

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;
}