Saltar al contenido

API

Ver como Markdown Editar en GitHub Documentación de 22946a5

shikiphp ofrece dos puntos de entrada: la fachada estática Shikiphp para los casos habituales y la instancia Highlighter para todo lo demás (salida HAST, gramáticas y temas personalizados, variantes de tema e introspección de paquetes).

La fachada Shikiphp

Shikiphp\Shikiphp es una fachada estática sencilla sobre un resaltador incluido que se crea de forma diferida y se almacena en caché.

Shikiphp::codeToHtml

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

Tokeniza $code y representa un bloque completo de <pre class="shiki …"> HTML. La matriz de opciones siempre contiene un lang, además de un mapa theme o themes, y cualquiera de las opciones de representación.

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

Devuelve la cuadrícula de tokens bidimensional sin procesar (una lista interna por línea) de objetos Shikiphp\Render\ThemedToken en lugar 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 que coincide con el nombre codeToTokensBase de Shiki.

Shikiphp::codeToTokensResult

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

Devuelve el resultado completo que refleja el codeToTokens de nivel superior de Shiki: la cuadrícula de tokens, los colores resueltos, el nombre del tema, el estilo raíz del tema dual y el estado gramatical final. Consulte TokensResult más abajo.

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

Tokeniza $code y devuelve el estado gramatical alcanzado al final (getLastGrammarState de Shiki). Vuelva a pasarlo mediante la opción grammarState para reanudar la tokenización de un fragmento posterior desde el mismo estado, útil para el resaltado incremental. Genera un error si lang es 'ansi' (ANSI no tiene estado gramatical).

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

Devuelve el Highlighter incluido y compartido, y lo crea en el primer uso. Úselo para acceder a los métodos de instancia que aparecen a continuación.

Shikiphp::use y Shikiphp::reset

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

use sustituye el Highlighter personalizado (por ejemplo, uno en el que haya cargado gramáticas o temas personalizados) para que la fachada lo use como delegado. reset borra la instancia almacenada en caché para que la siguiente llamada vuelva a crear el resaltador incluido predeterminado.

El Highlighter

Shikiphp\Highlighter ofrece la interfaz completa. Obtenga la instancia incluida y compartida con Shikiphp::highlighter(), o cree una explícitamente:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

Implementa codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult y getLastGrammarState con las mismas firmas que la fachada, además de lo siguiente.

Highlighter::codeToHast

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

Construye el árbol HAST que genera pre.shiki > code > (span.line > span)* Shiki, listo para recorrerlo, modificarlo o serializarlo. Esto es lo que codeToHtml serializa internamente.

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

Tokeniza una vez por tema y combina el resultado en variants por token, con claves según el tema, como hace Shiki con codeToTokensWithThemes. Requiere un mapa 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 y Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

Registra una gramática TextMate o un tema VS Code personalizado a partir de JSON decodificado. Consulta Idiomas y temas personalizados.

Información del paquete

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 muestran todos los ids disponibles (incluidos los del paquete y los personalizados que hayas registrado). bundledLanguages/bundledThemes muestran solo los ids incluidos en el paquete. Consulta Idiomas y Temas.

Objetos de valor

ThemedToken

Shikiphp\Render\ThemedToken es un fragmento de texto con estilo:

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 es una máscara de bits de Shikiphp\Theme\FontStyle (NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult es el valor que devuelve 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 contiene la pila de reglas del tokenizador (con claves por nombre de tema) para reanudar el resaltado desde un punto intermedio.

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