# Compatibiliteit en upgrades

Op deze pagina vindt u wat u moet weten voordat u upgradet of op exacte uitvoer vertrouwt: de runtimevereisten, welke release van TailwindCSS de port volgt, waarin TailwindPHP bewust afwijkt van TailwindCSS en de opmerkingen bij elke release. De volledige geschiedenis staat in [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## Vereisten

- **PHP 8.2 of hoger.** De testsuite draait op PHP 8.2, 8.3 en 8.4.
- **De extensies `ctype` en `mbstring`.** De compiler roept `ctype_*` en `mb_chr()` aan. Beide worden meegeleverd met de meeste builds van PHP en de officiële Docker-images, maar `composer.json` declareert ze nog niet ([#11](https://github.com/inline0/tailwindphp/issues/11)). Daardoor kan een build zonder deze extensies het pakket installeren, maar tijdens runtime mislukken.
- **Optioneel: `pcntl`** laat de modus `--watch` van CLI netjes stoppen bij `SIGINT`/`SIGTERM`. Zonder deze extensie werkt de watchmodus nog steeds.

Er zijn geen Node.js, FFI of native binaire bestanden nodig.

## Welke release van TailwindCSS wordt gevolgd

Release 1.7.0 volgt **TailwindCSS v4.3.3**. De upstream-repository is als git-submodule vastgezet in `reference/tailwindcss`, de testsuites zijn uit die vastgezette checkout gehaald en de 4,427-tests draaien bij elke push (zie [Prestaties en testen](https://tailwindphp.inline0.dev/nl/docs/advanced/performance)). De geporteerde plugins volgen `@tailwindcss/typography` en `@tailwindcss/forms`; de klassehulpmiddelen volgen clsx, tailwind-merge en CVA, elk op dezelfde manier vastgezet.

## Bekende verschillen met TailwindCSS

### Serialisatiedetails

De gegenereerde CSS komt overeen met de referentietestsuites. Enkele serialisatiedetails verschillen van wat de TailwindCSS CLI afdrukt; geen daarvan verandert de cascade:

- Leveranciersprefixen: waar de referentie zowel de geschreven `-webkit-*`-regel als een gegenereerde regel uitvoert, produceert TailwindPHP één regel.
- Naar een lager niveau omgezette pseudo-elementen (`::file-selector-button`, `::-webkit-datetime-edit-*`) blijven in hun geschreven selectorlijsten staan, in plaats van te worden opgesplitst in één regel per pseudo-element.
- Geschreven tekenreeksen met enkele aanhalingstekens behouden die enkele aanhalingstekens (`'Segoe UI'`) in plaats van te worden genormaliseerd naar dubbele aanhalingstekens.
- Samen voorkomende longhands worden niet gecombineerd tot een shorthand (de eigen uitvoer van Tailwind heeft dat nooit nodig).
- `.p-0` behoudt `padding: 0px` waar de referentie-CLI `padding: 0` uitvoert, omdat het geëxtraheerde testcorpus de vorm `0px` vastlegt. De minifier verkort dit tot `0`.

### Niet inbegrepen

TailwindPHP is een CSS-compiler. De editorhulpmiddelen uit het Tailwind-ecosysteem ontbreken (IntelliSense, automatisch aanvullen en klassen sorteren), evenals bronkaarten. Daarom heeft de CLI geen optie `--map`.

### Inhoud scannen

`tw::generate()` en `TailwindCompiler::generate()` lezen klassennamen alleen uit de attributen `class` en `className`. Gebruik voor klassennamen in tekenreeksen van PHP of JavaScript [`tw::extractCandidatesFromStrings()`](https://tailwindphp.inline0.dev/nl/docs/api#twextractcandidatesfromstrings) of `@source inline("…")`. Padvormen van `@source` worden genegeerd door de API en slechts gedeeltelijk ondersteund door de CLI (zie hieronder).

### Bekende problemen in de huidige release

| Gebied | Huidig gedrag | Probleem |
|---|---|---|
| CLI `@source` | Paden en globs worden niet toegepast; in plaats daarvan wordt de map van het invoerbestand gescand en `@source not` sluit niets uit. Zie [Wat de CLI scant](https://tailwindphp.inline0.dev/nl/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | Minificeert, net als `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| Lange opties van CLI | `--input file.css` (gescheiden door spaties) wordt genegeerd; gebruik `--input=file.css` of `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| Pluginvarianten | Varianten `addVariant()`/`matchVariant()` en de typografie-elementmodifiers (`prose-headings:` …) worden gecompileerd zonder hun selector | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| `@apply`-mixins | `@apply --my-mixin;` wordt verwijderd in plaats van doorgegeven | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| Referentie-imports | De uitvoer is leeg wanneer een referentie-import vóór de utilities-import staat; `@import "tailwindcss" reference` heeft geen effect | [#14](https://github.com/inline0/tailwindphp/issues/14) |

## Upgrade-opmerkingen

### 1.7.0

- **De uitvoer verandert byte voor byte** ten opzichte van 1.6.x, maar blijft functioneel gelijkwaardig aan de referentie van TailwindCSS v4.3.3. Zichtbare wijzigingen zijn onder andere:
  - Spatiëringsvermenigvuldigers: `p-1` produceert `padding: var(--spacing)` in plaats van een `calc()`; bij een vermenigvuldiger van `0` wordt een kale nul-lengtewaarde geproduceerd.
  - Breuken worden percentages: `w-1/2` produceert `width: 50%`.
  - Kleuren: de lichtheid van `oklch()`/`oklab()` wordt als percentage geserialiseerd (`oklch(62.3% .214 259.815)`); `white` en `black` worden verkort tot `#fff` en `#000`.
  - CSS2-pseudo-elementen worden met één dubbele punt geserialiseerd (`:before`, `:after`, `:first-letter`, `:first-line`).
  - Geneste regels van `@media`/`@supports`/`@container` worden ter plekke en in bronvolgorde afgevlakt in plaats van naar het einde te worden verplaatst; declaraties worden geordend zoals lightningcss ze ordent en overschaduwde dubbele declaraties worden verwijderd.
- **Cachesleutels op basis van uitvoer veranderen één keer.** De bestandscache van `tw::generate()` neemt de versie van TailwindPHP niet mee in de sleutel. Voer daarom na een upgrade `tw::clearCache()` uit (of wis de map die u als `cache` hebt opgegeven). De [cache voor compilerstatus](https://tailwindphp.inline0.dev/nl/docs/advanced/caching#compiler-state-cache) wordt automatisch ongeldig.
- **Nieuw:** `@variant` in de auteur-CSS, CSS-mixins in `@apply`, `@media reference` en `@import "…" reference`, de volledige `--value()`/`--modifier()`-engine voor functionele `@utility`, strengere validatie van `@utility`-namen en de optie `polyfills` van `tw::compile()`.

### 1.6.1

- **Nieuw:** het hulpprogramma `container` (`width: 100%` plus één `max-width` per breakpoint).
- Samengestelde `--tw-*`-variabelen (vertalen, schalen, roteren, scheeftrekken, filters en meer) zijn nu geregistreerd bij `@property`, zodat stylesheets die `@property`-regels bevatten en transformaties zoals `translate-x-7` in de browser werken.

### 1.6.0

- **Nieuw:** de blijvende cache voor compilerstatus (`stateCacheFile` op `tw::compile()` en `TailwindCompiler`, `StateCache\compileCssCached()`), plus de opgesplitste functies `parseCssState()`/`finalizeCssState()`/`compileParsed()`. Bestaande aanroepen werken precies als voorheen.

### 1.5.0

- Subklassen van `TailwindCompiler` die `generate()` of `css()` overschrijven, moeten de optionele parameter `bool $minify = false` toevoegen; PHP weigert overschrijvingen die een optionele parameter van een bovenliggende klasse weglaten.
- Geminificeerde uitvoer komt van de serializer. De geminificeerde bytes wijken daardoor enigszins af van 1.4.x (cachesleutels op basis van geminificeerde uitvoer veranderen één keer).
- **Nieuw:** `generateExact()` en `cssExact()` voor CSS per pagina vanuit één langlevende compiler.