# Kompatibilität und Upgrades

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](https://github.com/inline0/tailwindphp/blob/main/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](https://github.com/inline0/tailwindphp/issues/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](https://tailwindphp.inline0.dev/de/docs/advanced/performance)). 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()`](https://tailwindphp.inline0.dev/de/docs/api#twextractcandidatesfromstrings) 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](https://tailwindphp.inline0.dev/de/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Minifiziert wie `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Lange CLI-Optionen | `--input file.css` (durch Leerzeichen getrennt) wird ignoriert; verwende `--input=file.css` oder `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Plugin-Varianten | `addVariant()`/`matchVariant()`-Varianten und Modifikatoren für Typografieelemente (`prose-headings:` …) werden ohne ihren Selektor kompiliert | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| `@apply`-Mixins | `@apply --my-mixin;` wird verworfen statt weitergereicht | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Referenzimporte | Die Ausgabe ist leer, wenn ein Referenzimport vor dem Utilities-Import steht; `@import "tailwindcss" reference` hat keine Wirkung | [#14](https://github.com/inline0/tailwindphp/issues/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](https://tailwindphp.inline0.dev/de/docs/advanced/caching#compiler-state-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.