# shikiphp

shikiphp es una adaptación pura de PHP de [Shiki](https://shiki.style), el resaltador de sintaxis que colorea código con las mismas gramáticas y temas TextMate que VS Code. Tokeniza el código con las mismas **gramáticas TextMate** y lo colorea con los mismos **temas VS Code** que usa Shiki, generando el mismo HTML que Shiki 3.23.0, íntegramente en PHP.

Sin entorno de ejecución de Node. Sin extensiones PHP aparte de `json` y `mbstring`. Sin enlace nativo de Oniguruma. Sin ejecutar procesos JavaScript ni usar un API alojado.

```php
use Shikiphp\Shikiphp;

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

## Por qué shikiphp

El resaltado de sintaxis en el servidor con PHP suele implicar uno de tres compromisos: ejecutar Node, llamar a un API alojado o conformarse con un resaltador basado en expresiones regulares que no entiende realmente el idioma. Ninguna de esas opciones encaja bien en Laravel, WordPress ni en un proceso de compilación de sitios estáticos.

shikiphp elimina esos compromisos al portar el proceso real de Shiki a PHP:

- un tokenizador de gramáticas TextMate (adaptación fiel de
  [`vscode-textmate`](https://github.com/microsoft/vscode-textmate)), con
  idiomas incrustados, inyecciones y repositorios anidados
- resolución de temas VS Code con especificidad de selectores de ámbito y
  correspondencia con ámbitos superiores
- HTML compatible con Shiki: temas claro y oscuro mediante variables CSS, `codeToHast`,
  transformadores (todos los hooks), decoraciones, `colorReplacements`,
  `structure: 'inline'` y resaltado ANSI (`lang: 'ansi'`)
- el **paquete completo de Shiki**: todos los idiomas `tm-grammars` (235 y las 18
  gramáticas auxiliares que incorporan) y todos los temas `tm-themes` (65)

## Comparado con Shiki 3.23.0

El resultado no es «suficientemente parecido»: se comprueba frente a una versión fijada de Shiki.

| Paquete | Versión | Uso |
| --- | --- | --- |
| `shiki` | 3.23.0 | referencia, ejecutada con su motor de expresiones regulares JavaScript |
| `tm-grammars` | 1.31.15 | gramáticas incluidas |
| `tm-themes` | 1.12.2 | temas incluidos |
| `@shikijs/transformers` | 4.2.0 | pruebas de paridad de los transformadores |

Shiki es la referencia. El sistema de pruebas de regresión contiene **214 escenarios**, cada uno con una muestra en un idioma y un tema, y las opciones predeterminadas. Shiki y shikiphp resaltan cada escenario y las cadenas HTML resultantes deben ser idénticas tras quitar los espacios en blanco iniciales y finales. En conjunto, los escenarios abarcan 167 de las 253 gramáticas incluidas, `lang: 'ansi'` y los 65 temas. Las opciones (`structure`, `tabindex`, `colorReplacements`, temas dobles, `defaultColor` y demás), `codeToTokensWithThemes` y los transformadores incorporados se cubren con pruebas de paridad independientes, cuyos resultados esperados se capturaron con las mismas versiones de Shiki.

De ahí se desprenden dos limitaciones. El motor predeterminado de Shiki es Oniguruma compilado a WebAssembly, mientras que la referencia usa el motor de expresiones regulares JavaScript de Shiki, que es el motor que adapta shikiphp. Además, no se han comprobado las versiones posteriores de Shiki (la línea 4.x).

## Cómo funciona

shikiphp se basa en una copia incluida de un **motor de expresiones regulares JavaScript** escrito íntegramente en PHP, procedente de [`inline0/phasis`](https://github.com/inline0/phasis), que recibe los patrones de un port a PHP de [`oniguruma-to-es`](https://github.com/slevithan/oniguruma-to-es). El motor de expresiones regulares JavaScript de Shiki convierte los patrones Oniguruma de las gramáticas TextMate en JavaScript `RegExp`, por lo que un motor de expresiones regulares JS es la base natural: permite que shikiphp reproduzca la salida de ese motor posición por posición.

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

Consulta [Arquitectura](https://shikiphp.inline0.dev/es/docs/architecture) para ver el flujo completo.

## Requisitos

- PHP 8.2 o posterior (CI ejecuta el conjunto de pruebas en PHP 8.4)
- `ext-json` y `ext-mbstring` (ambos vienen incluidos en prácticamente todas las compilaciones de PHP)

## Próximos pasos

- [Primeros pasos](https://shikiphp.inline0.dev/es/docs/getting-started) — instala y renderiza tu primer bloque.
- [API](https://shikiphp.inline0.dev/es/docs/api) — todos los métodos disponibles.
- [Opciones](https://shikiphp.inline0.dev/es/docs/options) — todas las opciones que acepta `codeToHtml`.
- [Transformadores](https://shikiphp.inline0.dev/es/docs/transformers) — el flujo de hooks y los elementos integrados.
- [CLI](https://shikiphp.inline0.dev/es/docs/cli) — `bin/shikiphp highlight`, `langs` y `themes`.

## Licencia

MIT, copyright inline0. Las gramáticas y los temas TextMate incluidos conservan sus licencias originales.