본문으로 건너뛰기

API

Markdown으로 보기 GitHub에서 수정 문서 위치 22946a5

shikiphp은 두 가지 진입점을 제공합니다. 일반적인 경우를 위한 정적 Shikiphp 파사드와 그 외 모든 기능(HAST 출력, 사용자 지정 문법 및 테마, 테마 변형, 번들 검사)을 위한 Highlighter 인스턴스입니다.

Shikiphp 파사드

Shikiphp\Shikiphp은 지연 생성되고 캐시되는 번들 하이라이터를 감싼 얇은 정적 파사드입니다.

Shikiphp::codeToHtml

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

$code을 토큰화하고 완전한 <pre class="shiki …"> HTML 블록을 렌더링합니다. 옵션 배열에는 항상 lang이 포함되며, theme 또는 themes 맵 중 하나와 렌더링 옵션도 포함됩니다.

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

HTML 대신 Shikiphp\Render\ThemedToken 객체의 기본 2D 토큰 그리드(줄마다 내부 목록 하나)를 반환합니다.

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

Shiki의 codeToTokensBase 이름과 일치하는 codeToTokens의 별칭입니다.

Shikiphp::codeToTokensResult

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

Shiki의 최상위 codeToTokens를 반영하는 풍부한 결과를 반환합니다. 토큰 그리드와 확인된 색상, 테마 이름, 듀얼 테마 루트 스타일, 최종 문법 상태가 포함됩니다. 아래 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

$code을 토큰화하고 끝에 도달한 문법 상태(Shiki의 getLastGrammarState)를 반환합니다. 같은 상태에서 이후 조각의 토큰화를 재개하려면 grammarState 옵션으로 해당 상태를 전달하세요. 점진적 강조 표시에 유용합니다. lang이 'ansi'이면 오류를 발생시킵니다(ANSI에는 문법 상태가 없습니다).

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

처음 사용 시 생성되는 공유 번들 Highlighter을 반환합니다. 아래의 인스턴스 메서드에 접근할 때 사용하세요.

Shikiphp::use 및 Shikiphp::reset

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

use은 사용자 지정 Highlighter(예: 사용자 지정 문법이나 테마를 로드한 인스턴스)으로 교체하여 파사드가 해당 인스턴스에 위임하도록 합니다. reset는 캐시된 인스턴스를 지워 다음 호출에서 기본 번들 하이라이터를 다시 생성하게 합니다.

Highlighter

Shikiphp\Highlighter에는 전체 API가 포함됩니다. 공유 번들 인스턴스는 Shikiphp::highlighter()로 가져오거나 직접 만들 수 있습니다:

PHP
use Shikiphp\Highlighter;

$highlighter = Highlighter::createBundled();

파사드와 동일한 시그니처로 codeToHtml, codeToTokens, codeToTokensBase, codeToTokensResult, getLastGrammarState를 구현하며, 다음 기능도 제공합니다.

Highlighter::codeToHast

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

Shiki가 생성하는 pre.shiki > code > (span.line > span)* HAST 트리를 만들며, 직접 순회하거나 수정하거나 직렬화할 수 있습니다. 이는 codeToHtml가 내부적으로 직렬화하는 대상입니다.

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

테마마다 한 번씩 토큰화하고, 결과를 테마 키로 인덱싱된 토큰별 variants에 병합합니다. Shiki의 codeToTokensWithThemes를 따릅니다. 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 및 Highlighter::loadTheme

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

public function loadTheme(array $rawTheme): void

디코딩한 JSON에서 사용자 지정 TextMate 문법 또는 VS Code 테마를 등록하세요. 사용자 지정 언어 및 테마를 참조하세요.

번들 정보 확인

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은 사용자 지정 항목을 포함해 현재 사용할 수 있는 모든 ID를 보고합니다. bundledLanguages/bundledThemes은 번들에 포함된 ID만 보고합니다. 언어 및 테마를 참조하세요.

값 객체

ThemedToken

Shikiphp\Render\ThemedToken는 스타일이 적용된 텍스트 구간 하나입니다:

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는 Shikiphp\Theme\FontStyle의 비트마스크입니다(NONE, ITALIC, BOLD, UNDERLINE, STRIKETHROUGH).

TokensResult

Shikiphp\TokensResult는 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에는 토크나이저의 규칙 스택(테마 이름별로 키 지정)이 저장되어 있어 중간 지점부터 하이라이팅을 재개할 수 있습니다.

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