# Primeiros passos

## Instalação

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

shikiphp requer PHP 8.2 ou posterior com `ext-json` e `ext-mbstring` — ambos
ativados em quase todas as compilações de PHP. Nada mais: sem Node, sem vinculação nativa
Oniguruma e sem extensões adicionais.

## Seu primeiro bloco

A fachada estática `Shikiphp` é a maneira mais rápida de começar. Passe seu código, um id de
linguagem e um id de tema:

```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` retorna um bloco `<pre class="shiki …">` completo, com estilo próprio. As cores do
primeiro plano e do plano de fundo são inseridas em linha no `<pre>`, garantindo a renderização
correta sem uma folha de estilos adicional.

## Temas duplos (claro e escuro)

Em vez de um único `theme`, passe um mapa `themes`. shikiphp emite variáveis CSS
(como Shiki) para que um único bloco renderizado se adapte aos modos claro e escuro:

```php
use Shikiphp\Shikiphp;

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

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

Por padrão, as cores do tema `light` são as cores em linha e `dark` é
exposto por meio de variáveis `--shiki-dark`. Ative o tema escuro com uma pequena
quantidade de CSS — o mesmo trecho usado na documentação 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;
}
```

Você pode escolher qual tema será o padrão em linha com a opção
[`defaultColor`](https://shikiphp.inline0.dev/pt/docs/options#defaultcolor), ou definir `defaultColor: false`
para emitir apenas variáveis.

## IDs de idioma e aliases

Os idiomas são referenciados pelo id ou alias Shiki — `php`, `ts`, `js`,
`rust`, `python`, `html` e assim por diante. Consulte [Idiomas](https://shikiphp.inline0.dev/pt/docs/languages) para saber
como listar tudo o que vem incluído e [Temas](https://shikiphp.inline0.dev/pt/docs/themes) para ver os ids dos temas.

## Reutilizar o realçador de sintaxe

A fachada cria e armazena em cache, de forma preguiçosa, um `Highlighter` incluído no pacote; assim, chamadas
repetidas a `Shikiphp::codeToHtml` reutilizam os mesmos caches de gramática e tema. Se precisar do
API mais completo (saída HAST, gramáticas personalizadas, grades de tokens), obtenha a instância
diretamente:

```php
use Shikiphp\Shikiphp;

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

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

Consulte a [API](https://shikiphp.inline0.dev/pt/docs/api) para ver a API completa.