# Rendimiento y pruebas

TailwindPHP prioriza la corrección. Aplica y marca como `@port-deviation:performance` los cambios específicos de PHP que aceleran el proceso sin alterar la salida. La paridad con TailwindCSS se verifica continuamente con la propia suite de pruebas de Tailwind.

## Rendimiento

El port de PHP prioriza igualar la salida de TailwindCSS frente al rendimiento bruto, y el original de TypeScript sigue siendo más rápido en cualquier caso: el JIT de V8 compila las rutas más usadas a código nativo de una forma que PHP no puede igualar. Para generar CSS por solicitud o página, reutilice un compilador (consulte [generateExact()](https://tailwindphp.inline0.dev/es/docs/api#accumulating-vs-exact-generation)) y conserve su estado de construcción con [`stateCacheFile`](https://tailwindphp.inline0.dev/es/docs/advanced/caching#compiler-state-cache).

Algunas rutas más usadas tienen optimizaciones ajustadas manualmente que **conservan una salida idéntica**:

- **`ast.php` `toCss()`** — acumula fragmentos en una matriz y los `implode` una sola vez en lugar de concatenar cadenas repetidamente, y usa cadenas de sangría precalculadas.
- **`css-parser.php`** — compara caracteres directamente en vez de pasar por `ord()`, y lleva el seguimiento de las longitudes del búfer en lugar de volver a calcular `strlen()`.

Ambas están documentadas con `@port-deviation:performance` y sujetas a la suite de pruebas: no pueden cambiar el CSS generado.

### Pruebas de rendimiento

El directorio `benchmarks/` contiene un entorno de comparación. Ejecútelo con:

```bash
composer bench         # PHP vs TypeScript
composer bench:save    # write benchmarks/results.json
```

Resultados de ejemplo en PHP 8.4.5 / Node.js v22.17.0 (Apple M1):

| Prueba de rendimiento | PHP | TypeScript |
|-----------|-----|------------|
| `css-parser` en preflight.css | ~816 ops/s | ~15.45K ops/s (≈20× más rápido) |
| `toCss` | ~65.85K ops/s | ~2.59M ops/s (≈39× más rápido) |

TypeScript es más rápido en estas operaciones de bajo nivel, como cabía esperar. Para generar CSS de página completa — el caso de uso real — el rendimiento de PHP es suficiente (unos 14 ms por página en la ejecución de ejemplo). Con entradas idénticas repetidas, la [caché de archivos](https://tailwindphp.inline0.dev/es/docs/advanced/caching) elimina por completo el coste.

## Pruebas y paridad

Las pruebas garantizan que el port de PHP produzca la misma salida que TailwindCSS. Se combinan dos métodos.

**1. Pruebas basadas en extracción.** Los scripts de `test-coverage/` analizan los archivos `.test.ts` de TailwindCSS y extraen los casos de prueba a JSON. Luego, PHPUnit ejecuta esos casos con TailwindPHP y compara la salida con el CSS esperado. Como las expectativas proceden directamente del proyecto original, cualquier diferencia en el comportamiento de PHP se detecta como un fallo. Estas pruebas cubren las áreas complejas: utilidades, variantes, integración, funciones CSS y pruebas `ui.spec` en el navegador.

**2. Pruebas unitarias adaptadas manualmente.** Los archivos de prueba más sencillos de TypeScript (AST, análisis de CSS, escape, análisis de candidatos, análisis de valores, …) se adaptan directamente a PHP y se guardan junto a su código fuente como `*.test.php`, siguiendo la estructura y las comprobaciones de los originales.

El ciclo es **extraer → ejecutar → verificar**: volver a extraer desde la referencia actual de TailwindCSS, ejecutar la suite y detectar cualquier desviación como un fallo. Así, el port se mantiene sincronizado con el proyecto original y una actualización de TailwindCSS se puede validar automáticamente en vez de inspeccionarla manualmente. Las desviaciones hacen fallar CI.

```bash
composer extract   # re-extract test cases from the TailwindCSS reference
composer test      # run the full suite
```

Hay **4,427 pruebas superadas** a partir de la versión 1.7.0 (referencia de TailwindCSS v4.3.3):

| Suite | Pruebas | Fuente |
|-------|-------|--------|
| TailwindCSS extraídas (utilidades 706, variantes 164, índice 148, funciones CSS 64, `ui.spec` 68) | 1,150 | extraídas de `.test.ts` / `.spec.ts` |
| Cobertura de API (utilidades, modificadores, variantes, directivas, plugins, importaciones, `@source`, caché, API público) | 2,252 | `tests/` |
| Pruebas unitarias junto al código fuente (analizador, AST, candidatos, tema, utilidades, analizador de selectores, transformaciones de lightningcss, minificador) | 767 | ports de `*.test.php` y pruebas específicas de PHP |
| CLI (análisis de argumentos, salida, compilaciones) | 84 | `tests/Cli*Test.php` |
| Ports de plugins (tipografía, formularios) | 45 | `*.test.php` junto a los plugins |
| Bibliotecas complementarias (clsx, tailwind-merge, CVA) | 129 | suites de referencia |

## Calidad del código

El formato y el análisis estático se ejecutan mediante scripts de Composer:

```bash
composer lint      # Pint --test  (check formatting)
composer format    # Pint         (fix formatting)
composer analyse   # PHPStan      (static analysis, level 4)
composer quality   # lint + analyse
```

PHPStan se ejecuta en el nivel 4 (`phpstan.neon`), con una breve lista de patrones ignorados para las formas de matriz dinámicas que utiliza la arquitectura basada en funciones. Se analizan todos los archivos de código fuente; se excluyen los archivos de prueba.

Para conocer la estructura que verifican estas pruebas y dónde se registran las desviaciones, consulte [Arquitectura](https://tailwindphp.inline0.dev/es/docs/advanced/architecture).