# shikiphp

shikiphp é uma adaptação de [Shiki](https://shiki.style) escrita apenas em PHP, o realçador de sintaxe que colore código com as mesmas gramáticas TextMate e os mesmos temas de VS Code. Tokeniza o código com as mesmas **gramáticas TextMate** e o colore com os mesmos **temas de VS Code** usados por Shiki, produzindo o mesmo HTML de Shiki 3.23.0 — inteiramente em PHP.

Sem ambiente de execução Node. Sem extensões PHP além de `json` e `mbstring`. Sem
vinculação nativa Oniguruma. Sem executar processos JavaScript externos nem usar um API hospedado.

```php
use Shikiphp\Shikiphp;

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

## Por que shikiphp

O realce de sintaxe no servidor em PHP geralmente exige um de três
compromissos: executar Node, chamar uma API hospedada ou se contentar com um
realçador baseado em expressões regulares que não entende de fato a linguagem. Nenhuma dessas opções
se encaixa bem em uma etapa de compilação de Laravel, WordPress ou de site estático.

shikiphp elimina esse compromisso ao portar o pipeline real de Shiki para PHP:

- um tokenizador de gramática TextMate (uma adaptação fiel de
  [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), incluindo
  idiomas incorporados, injeções e repositórios aninhados
- resolução de temas VS Code com especificidade de seletores de escopo e
  correspondência de escopos pai
- Shiki-compatível HTML: temas claro/escuro por meio de variáveis CSS, `codeToHast`,
  transformadores (todos os hooks), decorações, `colorReplacements`,
  `structure: 'inline'` e realce ANSI (`lang: 'ansi'`)
- o **pacote Shiki completo** — todas as linguagens `tm-grammars` (235, além de 18
  gramáticas auxiliares incorporadas) e todos os temas `tm-themes` (65)

## Comparado com Shiki 3.23.0

A saída não é “boa o bastante”: ela é verificada com uma versão fixa de Shiki.

| Pacote | Versão | Uso |
| --- | --- | --- |
| `shiki` | 3.23.0 | referência, executada com seu mecanismo de expressões regulares JavaScript |
| `tm-grammars` | 1.31.15 | gramáticas incluídas no pacote |
| `tm-themes` | 1.12.2 | temas incluídos no pacote |
| `@shikijs/transformers` | 4.2.0 | testes de equivalência dos transformadores |

O próprio Shiki é a referência. O conjunto de testes de regressão contém **214 cenários**,
cada um com uma amostra em um idioma e um tema, usando as opções padrão. Cada
cenário é realçado por Shiki e por shikiphp, e as duas strings de HTML precisam
ser idênticas após a remoção dos espaços em branco iniciais e finais. Juntos, os
cenários abrangem 167 das 253 gramáticas incluídas no pacote, `lang: 'ansi'` e todos os 65
temas. As opções (`structure`, `tabindex`, `colorReplacements`, temas duplos,
`defaultColor` e as demais), `codeToTokensWithThemes` e os transformadores integrados são cobertos por testes
separados de equivalência, cuja saída esperada foi capturada das mesmas versões de Shiki.

Isso impõe dois limites. O mecanismo padrão de Shiki é Oniguruma compilado
para WebAssembly, enquanto a referência usa o mecanismo de expressões regulares JavaScript de Shiki,
que é o mecanismo para o qual shikiphp faz adaptações. Além disso, versões posteriores de Shiki (a linha 4.x) ainda
não foram verificadas.

## Como funciona

shikiphp é baseado em um mecanismo de expressões regulares puro PHP **JavaScript** incluído no código-fonte de
[`inline0/phasis`](https://github.com/inline0/phasis), alimentado por uma adaptação PHP de
[`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). O mecanismo de expressões regulares JavaScript de Shiki converte os padrões Oniguruma nas gramáticas TextMate em
JavaScript `RegExp`, então um mecanismo de expressões regulares JS é a base natural — permite que
shikiphp corresponda à saída desse mecanismo, deslocamento por deslocamento.

```
code → grammar tokenizer → theme resolver → themed tokens → HTML
              │
              └─ OnigScanner → PatternConverter (oniguruma-to-es) → Shikiphp\Regex (JS RegExp engine)
```

Consulte [Arquitetura](https://shikiphp.inline0.dev/pt/docs/architecture) para ver o pipeline completo.

## Requisitos

- PHP 8.2 ou posterior (a CI executa o conjunto de testes em PHP 8.4)
- `ext-json` e `ext-mbstring` (ambos incluídos em praticamente todas as compilações de PHP)

## Próximos passos

- [Primeiros passos](https://shikiphp.inline0.dev/pt/docs/getting-started) — instale e renderize seu primeiro bloco.
- [API](https://shikiphp.inline0.dev/pt/docs/api) — todos os métodos disponíveis.
- [Opções](https://shikiphp.inline0.dev/pt/docs/options) — todas as opções aceitas por `codeToHtml`.
- [Transformadores](https://shikiphp.inline0.dev/pt/docs/transformers) — o pipeline de hooks e os recursos integrados.
- [CLI](https://shikiphp.inline0.dev/pt/docs/cli) — `bin/shikiphp highlight`, `langs` e `themes`.

## Licença

MIT, direitos autorais de inline0. As gramáticas e os temas incluídos no pacote TextMate mantêm suas licenças de origem.