# shikiphp

shikiphp è un porting puro in PHP di [Shiki](https://shiki.style), l'evidenziatore di sintassi che colora il codice usando le stesse grammatiche TextMate e gli stessi temi di VS
Code. Suddivide il codice in token con le stesse **grammatiche TextMate** e lo colora con gli stessi **temi VS Code** usati da Shiki, producendo lo stesso HTML di Shiki 3.23.0, interamente in PHP.

Nessun runtime Node. Nessuna estensione PHP oltre a `json` e `mbstring`. Nessun binding nativo
Oniguruma. Nessuna chiamata a un processo JavaScript esterno e nessun API ospitato.

```php
use Shikiphp\Shikiphp;

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

## Perché shikiphp

L'evidenziazione della sintassi lato server in PHP comporta solitamente uno di tre
compromessi: eseguire Node, chiamare un API ospitato oppure accontentarsi di un
strumento di evidenziazione basato su espressioni regolari che in realtà non comprende il linguaggio. Nessuna di queste soluzioni si integra facilmente in un passaggio di build Laravel, WordPress o di un sito statico.

shikiphp elimina il compromesso trasferendo la pipeline reale di Shiki in PHP:

- un tokenizer grammaticale TextMate (un porting fedele di
  [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), con lingue incorporate, injection e repository annidati
- risoluzione dei temi VS Code con specificità dei selettori di scope e
  corrispondenza con gli scope padre
- Shiki compatibile con HTML: temi chiari e scuri tramite variabili CSS, `codeToHast`,
  transformer (tutti gli hook), decorazioni, `colorReplacements`,
  `structure: 'inline'` ed evidenziazione ANSI (`lang: 'ansi'`)
- il **bundle Shiki completo**: tutte le lingue `tm-grammars` (235, più 18
  grammatiche ausiliarie incorporate) e tutti i temi `tm-themes` (65)

## Confronto con Shiki 3.23.0

L'output non è «abbastanza simile»: viene confrontato con una release Shiki bloccata.

| Pacchetto | Versione | Uso |
| --- | --- | --- |
| `shiki` | 3.23.0 | riferimento, eseguito con il motore regex JavaScript |
| `tm-grammars` | 1.31.15 | grammatiche incluse |
| `tm-themes` | 1.12.2 | temi inclusi |
| `@shikijs/transformers` | 4.2.0 | test di parità dei transformer |

Shiki stesso funge da riferimento. L'harness di regressione contiene **214 scenari**,
ognuno costituito da un esempio in una lingua e un tema con le opzioni predefinite. Ogni scenario viene elaborato da Shiki e da shikiphp, e le due stringhe HTML devono
essere identiche dopo aver rimosso gli spazi iniziali e finali. Nel complesso, gli
scenari coprono 167 delle 253 grammatiche incluse, `lang: 'ansi'` e tutti i 65
temi. Le opzioni (`structure`, `tabindex`, `colorReplacements`, temi chiaro/scuro,
`defaultColor` e le altre), `codeToTokensWithThemes` e i transformer integrati sono coperti da test di parità
separati, il cui output atteso è stato acquisito dalle stesse versioni Shiki.

Ne conseguono due limiti. Il motore predefinito di Shiki è Oniguruma compilato in
WebAssembly, mentre il riferimento usa il motore regex JavaScript di Shiki, quello usato dai porting shikiphp. Inoltre, le release successive di Shiki (la linea 4.x) non sono
state verificate.

## Come funziona

shikiphp si basa su un motore regex JavaScript **PHP puro** incorporato dal codice sorgente di
[`inline0/phasis`](https://github.com/inline0/phasis), alimentato da un porting PHP di
[`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Il motore regex JavaScript di Shiki converte i pattern Oniguruma nelle grammatiche TextMate in JavaScript `RegExp`, quindi un motore regex JS è la base naturale: permette a shikiphp di corrispondere all'output di quel motore offset per offset.

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

Consultate [Architettura](https://shikiphp.inline0.dev/it/docs/architecture) per la pipeline completa.

## Requisiti

- PHP 8.2 o successivo (CI esegue la suite di test su PHP 8.4)
- `ext-json` e `ext-mbstring` (inclusi in quasi tutte le build PHP)

## Prossime tappe

- [Guida introduttiva](https://shikiphp.inline0.dev/it/docs/getting-started) — installazione e rendering del primo blocco.
- [API](https://shikiphp.inline0.dev/it/docs/api) — tutti i metodi disponibili.
- [Opzioni](https://shikiphp.inline0.dev/it/docs/options) — tutte le opzioni accettate da `codeToHtml`.
- [Transformer](https://shikiphp.inline0.dev/it/docs/transformers) — la pipeline degli hook e quelli integrati.
- [CLI](https://shikiphp.inline0.dev/it/docs/cli) — `bin/shikiphp highlight`, `langs` e `themes`.

## Licenza

MIT, copyright inline0. Le grammatiche e i temi TextMate inclusi mantengono le rispettive
licenze originali.