Zum Inhalt springen

Kompatibilität und Upgrades

Als Markdown anzeigen Auf GitHub bearbeiten Dokumentation zu 3843abd

Diese Seite fasst zusammen, was du wissen musst, bevor du ein Upgrade durchführst oder dich auf eine exakte Ausgabe verlässt: die Laufzeitanforderungen, welcher TailwindCSS-Version die Portierung folgt, wo TailwindPHP bewusst von TailwindCSS abweicht und die Hinweise zu jeder Version. Die vollständige Historie findest du in CHANGELOG.md.

Voraussetzungen

  • PHP 8.2 oder neuer. Die Testsuite läuft mit PHP 8.2, 8.3 und 8.4.
  • Die Erweiterungen ctype und mbstring. Der Compiler ruft ctype_* und mb_chr() auf. Beide sind in den meisten PHP-Builds und den offiziellen Docker-Images enthalten. composer.json führt sie jedoch noch nicht als Abhängigkeiten auf (#11), weshalb ein Build ohne diese Erweiterungen das Paket installiert, aber zur Laufzeit fehlschlägt.
  • Optional: pcntl. Damit wird der CLI-Modus des --watch bei SIGINT/SIGTERM sauber beendet. Ohne die Erweiterung funktioniert der Überwachungsmodus weiterhin.

Es kommen weder Node.js noch FFI oder native Binärdateien zum Einsatz.

Verfolgte TailwindCSS-Version

Release 1.7.0 verfolgt TailwindCSS v4.3.3. Das Upstream-Repository ist als git-Submodul in reference/tailwindcss fixiert, seine Testsuiten werden aus diesem fixierten Checkout extrahiert und die 4,427-Tests laufen bei jedem Push (siehe Leistung und Tests). Die portierten Plugins folgen @tailwindcss/typography und @tailwindcss/forms; die Klassen-Utilities orientieren sich an clsx, tailwind-merge und CVA. Alle sind auf dieselbe Weise fixiert.

Bekannte Unterschiede zu TailwindCSS

Details zur Serialisierung

Das generierte CSS stimmt mit den Referenz-Testsuiten überein. Einige Details der Serialisierung unterscheiden sich von der Ausgabe des TailwindCSS-CLI, ändern aber nicht die Kaskade:

  • Herstellerpräfixe: Gibt die Referenz sowohl die verfasste -webkit-*-Zeile als auch eine generierte Zeile aus, erzeugt TailwindPHP nur eine Zeile.
  • Herabgestufte Pseudoelemente (::file-selector-button, ::-webkit-datetime-edit-*) bleiben in ihren verfassten Selektorlisten, statt in je eine Regel pro Pseudoelement aufgeteilt zu werden.
  • Verfasste Strings in einfachen Anführungszeichen bleiben in einfachen Anführungszeichen ('Segoe UI'), statt in doppelte Anführungszeichen umgewandelt zu werden.
  • Gleichzeitig auftretende Langschrifteigenschaften werden nicht zu einer Kurzschrifteigenschaft zusammengefasst (die Tailwind-eigene Ausgabe benötigt das nicht).
  • .p-0 behält padding: 0px bei, während die Referenz mit CLI padding: 0 ausgibt, da der extrahierte Testkorpus die Form 0px festlegt. Der Minifizierer kürzt sie zu 0.

Nicht enthalten

TailwindPHP ist ein CSS-Compiler. Er umfasst weder die Editor-Werkzeuge des Tailwind-Ökosystems (IntelliSense, Autovervollständigung, Klassensortierung) noch Source-Maps. Daher hat das CLI keine --map-Option.

Inhalte durchsuchen

tw::generate() und TailwindCompiler::generate() lesen Klassennamen nur aus den Attributen class und className. Für Klassennamen in PHP- oder JavaScript-Strings verwende tw::extractCandidatesFromStrings() oder @source inline("…"). Pfadangaben in @source werden von API ignoriert und von CLI nur teilweise berücksichtigt (siehe unten).

Bekannte Probleme der aktuellen Version

Bereich Aktuelles Verhalten Problem
CLI @source Pfade und Glob-Muster werden nicht angewendet; stattdessen wird das Verzeichnis der Eingabedatei durchsucht, und @source not schließt nichts aus. Siehe Was CLI durchsucht #8
CLI --optimize Minifiziert wie --minify #9
Lange CLI-Optionen --input file.css (durch Leerzeichen getrennt) wird ignoriert; verwende --input=file.css oder -i file.css #13
Plugin-Varianten addVariant()/matchVariant()-Varianten und Modifikatoren für Typografieelemente (prose-headings: …) werden ohne ihren Selektor kompiliert #10
@apply-Mixins @apply --my-mixin; wird verworfen statt weitergereicht #12
Referenzimporte Die Ausgabe ist leer, wenn ein Referenzimport vor dem Utilities-Import steht; @import "tailwindcss" reference hat keine Wirkung #14

Hinweise zum Upgrade

1.7.0

  • Die Ausgabe unterscheidet sich byteweise von 1.6.x, ist aber funktional gleichwertig mit der TailwindCSS-Referenz v4.3.3. Zu den sichtbaren Änderungen zählen:
    • Abstands-Multiplikatoren: p-1 gibt padding: var(--spacing) statt eines calc() aus; ein Multiplikator von 0 ergibt eine einfache Länge von null.
    • Brüche werden zu Prozentwerten: w-1/2 gibt width: 50% aus.
    • Farben: Die Helligkeit von oklch()/oklab() wird als Prozentwert serialisiert (oklch(62.3% .214 259.815)); white und black werden zu #fff und #000 verkürzt.
    • Die Pseudoelemente aus CSS2 werden mit einem einzelnen Doppelpunkt serialisiert (:before, :after, :first-letter, :first-line).
    • Verschachtelte @media-/@supports-/@container-Regeln werden an Ort und Stelle und in Quellreihenfolge abgeflacht, statt ans Ende verschoben zu werden. Deklarationen werden in der Reihenfolge von lightningcss neu angeordnet; überschattete doppelte Deklarationen werden entfernt.
  • Ausgabebasierte Caches werden einmalig ungültig. Der Datei-Cache von tw::generate() berücksichtigt die TailwindPHP-Version nicht in seinem Schlüssel. Führe nach dem Upgrade daher tw::clearCache() aus (oder den Ordner, den du als cache übergeben hast). Der Compilerstatus-Cache wird automatisch ungültig.
  • Neu: @variant in Autor-CSS, CSS-Mixins in @apply, @media reference und @import "…" reference, die vollständige --value()-/--modifier()-Engine für funktionale @utility, strengere Validierung von @utility-Namen und die Option polyfills von tw::compile().

1.6.1

  • Neu: die container-Utility (width: 100% plus ein max-width pro Breakpoint).
  • Zusammengesetzte --tw-*-Variablen (translate, scale, rotate, skew, Filter und weitere) werden nun mit @property registriert. Dadurch erhalten Stylesheets diese @property-Regeln und Transformationen wie translate-x-7 werden im Browser wirksam.

1.6.0

  • Neu: der persistente Compiler-Statuscache (stateCacheFile für tw::compile() und TailwindCompiler, StateCache\compileCssCached()) sowie die aufgeteilten Funktionen parseCssState()/finalizeCssState()/compileParsed(). Bestehende Aufrufe verhalten sich unverändert.

1.5.0

  • Unterklassen von TailwindCompiler, die generate() oder css() überschreiben, müssen den optionalen Parameter bool $minify = false ergänzen; PHP lehnt Überschreibungen ab, die einen optionalen Parameter der übergeordneten Klasse weglassen.
  • Minifizierte Ausgaben stammen vom Serializer. Daher unterscheiden sich minifizierte Bytes leicht von 1.4.x (Caches mit Schlüsseln auf Basis minifizierter Ausgaben müssen einmalig geleert werden).
  • Neu: generateExact() und cssExact() für seitenbezogene CSS mit einem langlebigen Compiler.