# 快速入门

## 安装

```bash
composer require shikiphp/shikiphp
```

shikiphp 需要 PHP 8.2 或更高版本，以及 `ext-json` 和 `ext-mbstring`——几乎每个 PHP 构建都已启用这两项。无需其他依赖：不需要 Node、原生 Oniguruma 绑定或额外扩展。

## 第一个代码块

静态 `Shikiphp` 外观接口是最快的入门方式。传入代码、语言 id 和主题 id：

```php
use Shikiphp\Shikiphp;

$html = Shikiphp::codeToHtml(<<<'PHP'
<?php
function greet(string $name): string {
    return "Hello, {$name}!";
}
PHP, [
    'lang'  => 'php',
    'theme' => 'github-dark',
]);

echo $html;
```

`codeToHtml` 会返回完整且自带样式的 `<pre class="shiki …">` 块。前景色和背景色以内联方式写在 `<pre>` 上，因此无需额外样式表也能正确渲染。

## 双主题（亮色和暗色）

不传单个 `theme`，而是传入一个 `themes` 映射。shikiphp 会输出 CSS 变量（例如 Shiki），让同一个渲染块能适配亮色和暗色模式：

```php
use Shikiphp\Shikiphp;

$code = 'const answer: number = 42';

echo Shikiphp::codeToHtml($code, [
    'lang'   => 'ts',
    'themes' => ['light' => 'github-light', 'dark' => 'github-dark'],
]);
```

默认情况下，`light` 主题的颜色以内联方式作为默认值，而 `dark` 通过 `--shiki-dark` 变量公开。添加少量 CSS 即可启用暗色主题——同一段代码示例在 Shiki 文档中使用：

```css
html.dark .shiki,
html.dark .shiki span {
  color: var(--shiki-dark) !important;
  background-color: var(--shiki-dark-bg) !important;
  /* and font styles */
  font-style: var(--shiki-dark-font-style) !important;
  font-weight: var(--shiki-dark-font-weight) !important;
  text-decoration: var(--shiki-dark-text-decoration) !important;
}
```

你可以通过 [`defaultColor`](https://shikiphp.inline0.dev/zh/docs/options#defaultcolor) 选项选择以内联方式设为默认值的主题，也可以将 `defaultColor: false` 设为只输出变量。

## 语言 id 和别名

语言通过 Shiki id 或别名引用，例如 `php`、`ts`、`js`、`rust`、`python`、`html` 等。有关如何列出所有随附语言，请参见 [语言](https://shikiphp.inline0.dev/zh/docs/languages)；主题 id 请参见 [主题](https://shikiphp.inline0.dev/zh/docs/themes)。

## 重用高亮器

外观接口会按需创建并缓存捆绑的 `Highlighter`，因此多次调用 `Shikiphp::codeToHtml` 会重用同一组语法和主题缓存。如果需要功能更丰富的 API（HAST 输出、自定义语法、令牌网格），可以直接获取该实例：

```php
use Shikiphp\Shikiphp;

$code = 'fn main() {}';

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

完整接口说明请参见 [API](https://shikiphp.inline0.dev/zh/docs/api)。