# shikiphp

shikiphp est un portage pur-PHP de [Shiki](https://shiki.style), le moteur de coloration syntaxique qui colore le code avec les mêmes grammaires TextMate et thèmes que VS Code. Il tokenise le code avec les mêmes **grammaires TextMate** et le colore avec les mêmes **thèmes VS Code** qu’utilise Shiki, produisant le même HTML que Shiki 3.23.0 — entièrement en PHP.

Aucun environnement Node. Aucune extension PHP au-delà de `json` et `mbstring`. Aucune liaison native Oniguruma. Aucun lancement d’un processus JavaScript ni service API hébergé.

```php
use Shikiphp\Shikiphp;

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

## Pourquoi shikiphp

La coloration syntaxique côté serveur dans PHP implique généralement l’un de ces trois compromis : lancer Node, appeler un API hébergé ou se contenter d’un surligneur basé sur des expressions régulières qui ne comprend pas réellement le langage. Aucun ne s’intègre facilement à une étape de build Laravel, WordPress ou de site statique.

shikiphp élimine ces compromis en portant le véritable pipeline de Shiki vers PHP :

- un tokenizer de grammaire TextMate (portage fidèle de [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), avec langages intégrés, injections et dépôts imbriqués
- résolution de thèmes VS Code avec spécificité des sélecteurs de portée et correspondance des portées parentes
- HTML compatible Shiki : thèmes clair et sombre via les variables CSS, `codeToHast`, transformateurs (tous les hooks), décorations, `colorReplacements`, `structure: 'inline'` et coloration ANSI (`lang: 'ansi'`)
- le **bundle Shiki complet** — chaque langage `tm-grammars` (235, plus les 18 grammaires auxiliaires qu’ils intègrent) et chaque thème `tm-themes` (65)

## Comparé à Shiki 3.23.0

La sortie n’est pas « suffisamment proche » : elle est vérifiée par rapport à une version épinglée de Shiki.

| Paquet | Version | Utilisation |
| --- | --- | --- |
| `shiki` | 3.23.0 | référence, exécutée avec son moteur d’expressions régulières JavaScript |
| `tm-grammars` | 1.31.15 | grammaires fournies dans le bundle |
| `tm-themes` | 1.12.2 | thèmes fournis dans le bundle |
| `@shikijs/transformers` | 4.2.0 | tests de parité des transformateurs |

Shiki est lui-même la référence. Le banc de régression comprend **214 scénarios**, chacun correspondant à un exemple dans un langage et un thème avec les options par défaut. Chaque scénario est mis en évidence par Shiki et shikiphp ; les deux chaînes HTML doivent être identiques après suppression des espaces de début et de fin. Ensemble, les scénarios couvrent 167 des 253 grammaires du bundle, `lang: 'ansi'` et les 65 thèmes. Les options (`structure`, `tabindex`, `colorReplacements`, thèmes doubles, `defaultColor` et autres), `codeToTokensWithThemes` et les transformateurs intégrés sont couverts par des tests de parité distincts, dont les sorties attendues ont été capturées à partir des mêmes versions de Shiki.

Deux limites en découlent. Le moteur par défaut de Shiki est Oniguruma compilé en WebAssembly, tandis que la référence utilise le moteur d’expressions régulières JavaScript de Shiki, celui que porte shikiphp. Les versions ultérieures de Shiki (la branche 4.x) n’ont pas été vérifiées.

## Fonctionnement

shikiphp repose sur un moteur regex pur-PHP **JavaScript** intégré, issu de
[`inline0/phasis`](https://github.com/inline0/phasis), porté depuis PHP
[`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). Le moteur regex de Shiki
JavaScript convertit les motifs Oniguruma des grammaires TextMate en
JavaScript `RegExp` : un moteur regex JS s’impose donc, pour permettre à
shikiphp de reproduire exactement ses décalages.

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

Consultez [Architecture](https://shikiphp.inline0.dev/fr/docs/architecture) pour découvrir le pipeline complet.

## Prérequis

- PHP 8.2 ou version ultérieure (l'intégration continue exécute la suite de tests sur PHP 8.4)
- `ext-json` et `ext-mbstring` (tous deux fournis avec presque toutes les versions de PHP)

## Pour la suite

- [Prise en main](https://shikiphp.inline0.dev/fr/docs/getting-started) — installez et affichez votre premier bloc.
- [API](https://shikiphp.inline0.dev/fr/docs/api) — toutes les méthodes disponibles.
- [Options](https://shikiphp.inline0.dev/fr/docs/options) — toutes les options acceptées par `codeToHtml`.
- [Transformateurs](https://shikiphp.inline0.dev/fr/docs/transformers) — le pipeline de hooks et les éléments intégrés.
- [CLI](https://shikiphp.inline0.dev/fr/docs/cli) — `bin/shikiphp highlight`, `langs` et `themes`.

## Licence

MIT, droits d'auteur inline0. Les grammaires et thèmes TextMate intégrés conservent leurs licences
amont.