Vai al contenuto

Compatibilità e aggiornamenti

Visualizza come Markdown Modifica su GitHub Documentazione di 3843abd

Questa pagina raccoglie le informazioni da conoscere prima di aggiornare o fare affidamento su un output esatto: i requisiti di runtime, le versioni di TailwindCSS seguite dal port, le differenze intenzionali di TailwindPHP rispetto a TailwindCSS e le note per ogni versione. La cronologia completa è in CHANGELOG.md.

Requisiti

  • PHP 8.2 o versioni successive. La suite di test viene eseguita su PHP 8.2, 8.3 e 8.4.
  • Le estensioni ctype e mbstring. Il compilatore chiama ctype_* e mb_chr(). Entrambe sono incluse nella maggior parte delle build di PHP e nelle immagini ufficiali Docker, ma composer.json non le dichiara ancora (#11), quindi una build che ne è priva installa il pacchetto ma poi fallisce durante l'esecuzione.
  • Facoltativo: pcntl consente alla modalità --watch di CLI di arrestarsi correttamente su SIGINT/SIGTERM. Senza, la modalità di monitoraggio funziona comunque.

Non sono necessari Node.js, FFI o binari nativi.

Quale versione di TailwindCSS viene seguita

La versione 1.7.0 segue TailwindCSS v4.3.3. Il repository upstream è bloccato come sottomodulo git in reference/tailwindcss; le suite di test vengono estratte da quel checkout bloccato e i test 4,427 vengono eseguiti a ogni push (vedere Prestazioni e test). I plugin portati seguono @tailwindcss/typography e @tailwindcss/forms, mentre le utility per le classi seguono clsx, tailwind-merge e CVA, tutti bloccati allo stesso modo.

Differenze note rispetto a TailwindCSS

Dettagli di serializzazione

CSS generato corrisponde alle suite di test di riferimento. Alcuni dettagli di serializzazione differiscono da quanto prodotto da TailwindCSS CLI, senza modificare la cascata:

  • Prefissi vendor: quando il riferimento emette sia la riga -webkit-* originale sia una generata, TailwindPHP emette una sola riga.
  • Gli pseudo-elementi trasformati per le versioni precedenti (::file-selector-button, ::-webkit-datetime-edit-*) restano negli elenchi di selettori originali invece di essere separati in una regola per pseudo-elemento.
  • Le stringhe originali tra apici singoli restano tali ('Segoe UI') invece di essere normalizzate con doppi apici.
  • Le proprietà longhand presenti insieme non vengono combinate in una proprietà shorthand (l'output di Tailwind non ne ha mai bisogno).
  • .p-0 mantiene padding: 0px dove il riferimento CLI emette padding: 0, perché il corpus di test estratto fissa la forma 0px. Il minificatore la accorcia in 0.

Funzionalità non incluse

TailwindPHP è un compilatore CSS. Esclude gli strumenti per l'editor dell'ecosistema Tailwind (IntelliSense, completamento automatico e ordinamento delle classi) e le source map, quindi la CLI non offre un'opzione --map.

Analisi dei contenuti

tw::generate() e TailwindCompiler::generate() leggono i nomi delle classi solo dagli attributi class e className. Per i nomi delle classi contenuti in stringhe PHP o JavaScript, usate tw::extractCandidatesFromStrings() oppure @source inline("…"). Le forme di percorso di @source vengono ignorate da API e considerate solo in parte da CLI (vedi sotto).

Problemi noti nella versione attuale

Area Comportamento attuale Problema
CLI @source I percorsi e i pattern glob non vengono applicati; viene invece analizzata la directory del file di input e @source not non esclude nulla. Consultate Cosa analizza CLI #8
CLI --optimize Esegue la minificazione, come --minify #9
Opzioni lunghe di CLI --input file.css (separato da spazi) viene ignorato; usate --input=file.css o -i file.css #13
Varianti dei plugin Le varianti addVariant()/matchVariant() e i modificatori degli elementi tipografici (prose-headings: …) vengono compilati senza il relativo selettore #10
Mixins @apply @apply --my-mixin; viene eliminato invece di essere mantenuto #12
Import di riferimento L'output è vuoto se un import di riferimento precede l'import delle utilità; @import "tailwindcss" reference non ha effetto #14

Note sugli aggiornamenti

1.7.0

  • L'output cambia byte per byte rispetto a 1.6.x, pur restando funzionalmente equivalente al riferimento TailwindCSS v4.3.3. Tra le differenze visibili:
    • Moltiplicatori di spaziatura: p-1 emette padding: var(--spacing) anziché un calc(); un moltiplicatore di 0 emette invece una lunghezza pari a zero senza unità.
    • Le frazioni diventano percentuali: w-1/2 emette width: 50%.
    • Colori: la luminosità di oklch()/oklab() viene serializzata come percentuale (oklch(62.3% .214 259.815)); white e black diventano rispettivamente #fff e #000.
    • Gli pseudo-elementi CSS2 vengono serializzati con un solo due punti (:before, :after, :first-letter, :first-line).
    • Le regole @media/@supports/@container annidate vengono appiattite sul posto, nell'ordine del sorgente, invece di essere spostate alla fine; le dichiarazioni vengono riordinate secondo l'ordine di lightningcss e le dichiarazioni duplicate con valori sovrascritti vengono rimosse.
  • Le cache basate sull'output vengono invalidate una volta. La chiave della cache su file di tw::generate() non include la versione di TailwindPHP, quindi dopo l'aggiornamento eseguite tw::clearCache() (o svuotate la directory passata come cache). La cache dello stato del compilatore si invalida automaticamente.
  • Novità: @variant nel CSS dell'autore, mixins CSS in @apply, @media reference e @import "…" reference, il motore completo --value()/--modifier() per @utility funzionali, convalida più rigorosa dei nomi @utility e l'opzione polyfills di tw::compile().

1.6.1

  • Novità: l'utilità container (width: 100% più un max-width per ogni punto di interruzione).
  • Le variabili --tw-* composte (translate, scale, rotate, skew, filtri e altre) sono ora registrate con @property, così i fogli di stile acquisiscono queste regole @property e trasformazioni come translate-x-7 hanno effetto nel browser.

1.6.0

  • Novità: la cache persistente dello stato del compilatore (stateCacheFile su tw::compile() e TailwindCompiler, StateCache\compileCssCached()) e le funzioni separate parseCssState()/finalizeCssState()/compileParsed(). Le chiamate esistenti si comportano esattamente come prima.

1.5.0

  • Le sottoclassi di TailwindCompiler che sovrascrivono generate() o css() devono aggiungere il parametro facoltativo bool $minify = false; PHP rifiuta le sovrascritture che omettono un parametro facoltativo della classe genitore.
  • L'output minificato proviene dal serializzatore, quindi differisce leggermente byte per byte da 1.4.x (le cache basate sull'output minificato vengono invalidate una volta).
  • Novità: generateExact() e cssExact() per CSS separati per pagina da un unico compilatore a lunga durata.