# Guida introduttiva

## Installazione

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

shikiphp richiede PHP 8.2 o versioni successive con `ext-json` e `ext-mbstring`, entrambi
abilitati in quasi tutte le build PHP. Nient'altro: niente Node, nessun binding nativo
Oniguruma e nessun'estensione aggiuntiva.

## Il primo blocco

La facade statica `Shikiphp` è il modo più rapido per iniziare. Passate il codice, un id
lingua e un id 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` restituisce un blocco `<pre class="shiki …">` completo e formattato. I colori di primo piano e di sfondo sono specificati in linea sull'`<pre>`, quindi il blocco viene visualizzato correttamente senza bisogno di fogli di stile aggiuntivi.

## Temi chiaro e scuro

Invece di un singolo `theme`, passate una mappa `themes`. shikiphp genera variabili CSS
(come Shiki), così un singolo blocco visualizzato si adatta alla modalità chiara e scura:

```php
use Shikiphp\Shikiphp;

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

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

Per impostazione predefinita, i colori del tema `light` sono quelli in linea e `dark` viene
esposto tramite variabili `--shiki-dark`. Attivate il tema scuro con una piccola quantità
di CSS: lo stesso frammento di codice Shiki documenta:

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

Potete scegliere quale tema usare come predefinito in linea con l'opzione
[`defaultColor`](https://shikiphp.inline0.dev/it/docs/options#defaultcolor) oppure impostare `defaultColor: false`
per generare solo variabili.

## Id di lingua e alias

Le lingue sono indicate dal loro id Shiki o da un alias: `php`, `ts`, `js`,
`rust`, `python`, `html` e così via. Consultate [Lingue](https://shikiphp.inline0.dev/it/docs/languages) per sapere
come elencare tutto ciò che è incluso, e [Temi](https://shikiphp.inline0.dev/it/docs/themes) per gli id dei temi.

## Riutilizzare l'evidenziatore

La facade crea e memorizza nella cache in modo differito un `Highlighter` incluso, quindi le chiamate
ripetute a `Shikiphp::codeToHtml` riutilizzano le stesse cache di grammatiche e temi. Se vi serve
l'API più completo (output HAST, grammatiche personalizzate, griglie di token), recuperate direttamente l'istanza:

```php
use Shikiphp\Shikiphp;

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

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

Consultate la [API](https://shikiphp.inline0.dev/it/docs/api) per la documentazione completa.