API
shikiphpには2つの入口があります。一般的な用途向けの静的Shikiphpファサードと、それ以外のすべてに対応するHighlighterインスタンスです（HAST出力、カスタム文法とテーマ、テーマバリアント、バンドルの詳細調査など）。
Shikiphpファサード
Shikiphp\Shikiphpは、遅延作成されキャッシュされるバンドル済みハイライターを覆う薄い静的ファサードです。
Shikiphp::codeToHtml
public static function codeToHtml(string $code, array $options): string
$codeをトークン化し、完全な<pre class="shiki …">HTMLブロックをレンダリングします。options配列には必ずlangと、themeまたはthemesマップのいずれかを指定し、レンダリングのオプションも指定できます。
use Shikiphp\Shikiphp;
echo Shikiphp::codeToHtml($code, ['lang' => 'php', 'theme' => 'github-dark']);
Shikiphp::codeToTokens
/** @return list<list<ThemedToken>> */
public static function codeToTokens(string $code, array $options): array
Shikiphp\Render\ThemedTokenオブジェクトで構成される、行ごとに内側のリストが分かれた2Dトークングリッドを返します。HTMLは返しません。
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
/** @return list<list<ThemedToken>> */
public static function codeToTokensBase(string $code, array $options): array
ShikiのcodeToTokensBaseという名前に合わせた、codeToTokensの別名です。
Shikiphp::codeToTokensResult
public static function codeToTokensResult(string $code, array $options): TokensResult
ShikiのトップレベルcodeToTokensに対応する詳細な結果を返します。トークングリッドに加え、解決済みの色、テーマ名、デュアルテーマのルートスタイル、最終的な文法状態を含みます。以下のTokensResultを参照してください。
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
public static function getLastGrammarState(string $code, array $options): GrammarState
$codeをトークン化し、末尾に到達した文法状態（ShikiのgetLastGrammarState）を返します。同じ状態から後続の断片のトークン化を再開するには、grammarStateオプションに渡します。インクリメンタルなハイライトに便利です。langが'ansi'の場合は例外をスローします（ANSIには文法状態がありません）。
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
public static function highlighter(): Highlighter
共有のバンドル済みHighlighterを返し、初回利用時には作成します。下記のインスタンスメソッドを使う際に利用してください。
Shikiphp::useとShikiphp::reset
public static function use(Highlighter $highlighter): void
public static function reset(): void
useはカスタムHighlighterに切り替え、ファサードからそのオブジェクトに処理を委譲します（カスタム文法やテーマを読み込ませたものなど）。resetはキャッシュ済みインスタンスをクリアし、次の呼び出しでデフォルトのバンドル済みハイライターを再構築します。
Highlighter
Shikiphp\Highlighterはすべての機能を備えています。共有のバンドル済みインスタンスはShikiphp::highlighter()で取得するか、明示的に作成します。
use Shikiphp\Highlighter;
$highlighter = Highlighter::createBundled();
ファサードと同じシグネチャでcodeToHtml、codeToTokens、codeToTokensBase、codeToTokensResult、getLastGrammarStateを実装し、さらに以下の機能を備えます。
Highlighter::codeToHast
public function codeToHast(string $code, array $options): \Shikiphp\Hast\Element
Shikiが構築するpre.shiki > code > (span.line > span)*HASTツリーを作成します。自身で走査、変更、シリアライズできます。codeToHtmlが内部でシリアライズするのもこのツリーです。
use Shikiphp\Shikiphp;
$hast = Shikiphp::highlighter()->codeToHast($code, [
'lang' => 'rust',
'theme' => 'nord',
]);
Highlighter::codeToTokensWithThemes
/** @return list<list<ThemedTokenWithVariants>> */
public function codeToTokensWithThemes(string $code, array $options): array
テーマごとに一度だけトークン化し、テーマキーを使って結果をトークンごとのvariantsに統合します。ShikiのcodeToTokensWithThemesに対応しています。themesマップが必要です。
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とHighlighter::loadTheme
public function loadGrammar(
array $rawTmLanguage,
?string $langId = null,
array $aliases = [],
array $embedded = [],
): void
public function loadTheme(array $rawTheme): void
デコード済みのJSONからカスタムTextMate文法またはVS Codeテーマを登録します。カスタム言語とテーマを参照してください。
バンドルの詳細調査
/** @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は現在利用可能なすべてのID（バンドル済みと登録済みのカスタム項目）を報告します。bundledLanguages/bundledThemesは同梱されているIDのみを報告します。言語とテーマを参照してください。
値オブジェクト
ThemedToken
Shikiphp\Render\ThemedTokenは、スタイルが適用されたテキストのひとまとまりです。
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はShikiphp\Theme\FontStyleから作られたビットマスクです（NONE、ITALIC、BOLD、UNDERLINE、STRIKETHROUGH）。
TokensResult
Shikiphp\TokensResultはcodeToTokensResultの戻り値です。
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はトークナイザーのルールスタックをテーマ名で管理し、中間地点からハイライトを再開できるようにします。
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;
}