# Compatibilidad y actualización

Esta página reúne lo que debe saber antes de actualizar o depender de una salida exacta: los requisitos del entorno de ejecución, qué versión de TailwindCSS sigue el port, en qué aspectos TailwindPHP difiere deliberadamente de TailwindCSS y las notas de cada versión. El historial completo está en [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## Requisitos

- **PHP 8.2 o posterior.** El conjunto de pruebas se ejecuta en PHP 8.2, 8.3 y 8.4.
- **Las extensiones `ctype` y `mbstring`.** El compilador usa `ctype_*` y `mb_chr()`. Ambas vienen incluidas en la mayoría de las compilaciones de PHP y en las imágenes oficiales de Docker, pero `composer.json` aún no las declara ([#11](https://github.com/inline0/tailwindphp/issues/11)), así que una compilación sin ellas instala el paquete, pero falla en tiempo de ejecución.
- **Opcional: `pcntl`** permite que el modo `--watch` del CLI se detenga correctamente ante `SIGINT`/`SIGTERM`. El modo de observación funciona sin esta opción.

No intervienen Node.js, FFI ni binarios nativos.

## Versión de TailwindCSS que se sigue

La versión 1.7.0 sigue **TailwindCSS v4.3.3**. El repositorio original está fijado como submódulo de git en `reference/tailwindcss`; sus conjuntos de pruebas se extraen de esa versión fijada y las pruebas de 4,427 se ejecutan en cada push (consulte [Rendimiento y pruebas](https://tailwindphp.inline0.dev/es/docs/advanced/performance)). Los plugins portados siguen `@tailwindcss/typography` y `@tailwindcss/forms`; las utilidades de clase siguen clsx, tailwind-merge y CVA, todos fijados del mismo modo.

## Diferencias conocidas con TailwindCSS

### Detalles de serialización

El CSS generado coincide con los conjuntos de pruebas de referencia. Algunos detalles de serialización difieren de lo que muestra TailwindCSS CLI, pero ninguno afecta la cascada:

- Prefijos de proveedor: cuando la referencia genera tanto la línea `-webkit-*` escrita por el autor como otra generada, TailwindPHP genera una sola línea.
- Los seudoelementos reducidos de nivel (`::file-selector-button`, `::-webkit-datetime-edit-*`) permanecen en las listas de selectores originales en vez de separarse en una regla por seudoelemento.
- Las cadenas originales entre comillas simples siguen con comillas simples (`'Segoe UI'`) en vez de normalizarse a comillas dobles.
- Las propiedades longhand que aparecen juntas no se combinan en una propiedad abreviada (la salida de Tailwind no lo necesita).
- `.p-0` conserva `padding: 0px` cuando la referencia CLI genera `padding: 0`, porque el corpus de pruebas extraído fija el formato `0px`. El minificador lo acorta a `0`.

### No incluido

TailwindPHP es un compilador de CSS. Deja fuera las herramientas del editor del ecosistema de Tailwind (IntelliSense, autocompletado y ordenación de clases) y los mapas de origen, por lo que CLI no tiene una opción `--map`.

### Análisis del contenido

`tw::generate()` y `TailwindCompiler::generate()` solo leen nombres de clase de los atributos `class` y `className`. Para nombres de clase incluidos en cadenas PHP o JavaScript, use [`tw::extractCandidatesFromStrings()`](https://tailwindphp.inline0.dev/es/docs/api#twextractcandidatesfromstrings) o `@source inline("…")`. El API ignora las rutas de `@source`, mientras que el CLI solo las respeta parcialmente (consulte más abajo).

### Problemas conocidos de la versión actual

| Área | Comportamiento actual | Problema |
|---|---|---|
| CLI `@source` | No se aplican rutas ni patrones glob; se analiza el directorio del archivo de entrada y `@source not` no excluye nada. Consulte [Qué analiza CLI](https://tailwindphp.inline0.dev/es/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Minifica, igual que `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Opciones largas de CLI | Se ignora `--input file.css` (separado por espacios); use `--input=file.css` o `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Variantes de plugins | Las variantes `addVariant()`/`matchVariant()` y los modificadores de elementos tipográficos (`prose-headings:` …) se compilan sin su selector | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| Mixins de `@apply` | Se descarta `@apply --my-mixin;` en vez de pasarse tal cual | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Importaciones de referencia | La salida está vacía si una importación de referencia precede a la importación de utilidades; `@import "tailwindcss" reference` no tiene efecto | [#14](https://github.com/inline0/tailwindphp/issues/14) |

## Notas de actualización

### 1.7.0

- **La salida cambia byte a byte** con respecto a 1.6.x, aunque sigue siendo funcionalmente equivalente a la referencia TailwindCSS v4.3.3. Entre los cambios visibles:
  - Multiplicadores de espaciado: `p-1` genera `padding: var(--spacing)` en vez de un `calc()`, y un multiplicador de `0` genera una longitud de cero sin unidad.
  - Las fracciones se convierten en porcentajes: `w-1/2` genera `width: 50%`.
  - Colores: la luminosidad de `oklch()`/`oklab()` se serializa como porcentaje (`oklch(62.3% .214 259.815)`); `white` y `black` se acortan a `#fff` y `#000`.
  - Los seudoelementos de CSS2 se serializan con dos puntos simples (`:before`, `:after`, `:first-letter`, `:first-line`).
  - Las reglas anidadas de `@media`/`@supports`/`@container` se aplanan en su lugar y en el orden del código fuente, en vez de trasladarse al final; las declaraciones se reordenan como lo hace lightningcss y se eliminan las declaraciones duplicadas que quedan ocultas.
- **Las cachés basadas en la salida se invalidan una vez.** La clave de la caché de archivos de `tw::generate()` no incluye la versión de TailwindPHP, así que ejecute `tw::clearCache()` (o el directorio que indicó como `cache`) después de actualizar. La [caché del estado del compilador](https://tailwindphp.inline0.dev/es/docs/advanced/caching#compiler-state-cache) se invalida automáticamente.
- **Nuevo:** `@variant` en CSS de autor, mixins CSS en `@apply`, `@media reference` y `@import "…" reference`, el motor completo de `--value()`/`--modifier()` para `@utility` funcional, validación más estricta de nombres `@utility` y la opción `polyfills` de `tw::compile()`.

### 1.6.1

- **Nuevo:** la utilidad `container` (`width: 100%` más un `max-width` por punto de interrupción).
- Las variables `--tw-*` compuestas (translate, scale, rotate, skew, filtros y otras) ahora se registran con `@property`, de modo que las hojas de estilos incorporan esas reglas `@property` y las transformaciones, como `translate-x-7`, funcionan en el navegador.

### 1.6.0

- **Nuevo:** la caché persistente del estado del compilador (`stateCacheFile` en `tw::compile()` y `TailwindCompiler`, `StateCache\compileCssCached()`) y las funciones separadas `parseCssState()`/`finalizeCssState()`/`compileParsed()`. Las llamadas existentes funcionan exactamente igual que antes.

### 1.5.0

- Las subclases de `TailwindCompiler` que redefinan `generate()` o `css()` deben añadir el parámetro opcional `bool $minify = false`; PHP rechaza las redefiniciones que omiten un parámetro opcional de la clase base.
- La salida minificada ahora procede del serializador, por lo que los bytes difieren ligeramente de 1.4.x (las cachés basadas en la salida minificada se invalidan una vez).
- **Nuevo:** `generateExact()` y `cssExact()` para obtener CSS por página desde un único compilador de larga duración.