Saltar al contenido

Compatibilidad y actualización

Ver como Markdown Editar en GitHub Documentación de 3843abd

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.

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), 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). 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() 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 #8
CLI --optimize Minifica, igual que --minify #9
Opciones largas de CLI Se ignora --input file.css (separado por espacios); use --input=file.css o -i file.css #13
Variantes de plugins Las variantes addVariant()/matchVariant() y los modificadores de elementos tipográficos (prose-headings: …) se compilan sin su selector #10
Mixins de @apply Se descarta @apply --my-mixin; en vez de pasarse tal cual #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

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 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.