Arkkitehtuuri

Näytä Markdown-muodossa Muokkaa palvelussa GitHub Dokumentaatio: 3843abd

TailwindPHP on 1:1-siirros. Koodikanta jäljittelee TailwindCSS:n omaa rakennetta — samat tiedostonimet ja sama järjestys — ja eristää osat, joita ei voi siirtää suoraan (PHP:sta puuttuvat Rust ja V8), hakemistoon src/_tailwindphp/. Tällä sivulla käydään läpi käännösputki, lähdekoodin hakemistorakenne, lightningcss-uudelleentoteutus ja poikkeamien dokumentointikäytäntö.

Käsittelyputki

CSS:n generointi koostuu vaiheista. Erillistä koostamisvaihetta ei ole — jokainen tw::generate()-kutsu suorittaa koko putken.

Koodi

CSS input          (@import "tailwindcss"; @theme { … })
  │
  ▼
┌──────────────┐
│  Parse CSS   │  css-parser.php → ast.php nodes
└──────┬───────┘
       ▼  design system (theme, utilities, variants)
┌──────────────┐
│ Scan content │  candidate.php — extract class names from HTML
└──────┬───────┘
       ▼  candidates
┌──────────────┐
│   Compile    │  compile.php — candidate → AST, via design-system.php
└──────┬───────┘
       ▼  AST
┌──────────────┐
│   Optimize   │  _tailwindphp/LightningCss.php — nesting, @media, calc()
└──────┬───────┘
       ▼
┌──────────────┐
│  Serialize   │  ast.php toCss()   (minified when requested)
└──────┬───────┘
       ▼
CSS output

Jäsennä. css-parser.php lukee CSS-syötteen — @import, @theme, @utility, @layer ja raakamuotoiset säännöt — ast.php-solmujen abstraktiksi syntaksipuuksi (tyylisäännöt, at-säännöt ja määritykset). @import-direktiivit virtuaalimoduuleille (tailwindcss, tailwindcss/preflight, …) ja tiedostopolut ratkaistaan ja korvataan tässä vaiheessa.

Rakenna suunnittelujärjestelmä. theme.php ratkaisee teeman arvot (värit, välit, katkaisukohdat) jäsennetyistä @theme-lohkoista ja oletusarvoista. design-system.php on keskeinen rekisteri, joka yhdistää teeman apuluokka- ja varianttihakuihin, jotka määritellään kohteissa utilities.php ja variants.php.

Käy sisältö läpi. candidate.php poimii luokkanimikandidaatit annetusta sisällöstä (HTML, mallit) ja jäsentää kunkin osiin — perusapuluokka, variantit, muokkaimet, mielivaltaiset arvot ja tärkeystunniste.

Käännä. compile.php muuntaa kunkin ehdokkaan syntaksipuun solmuiksi etsimällä sen suunnittelujärjestelmästä ja soveltamalla sen variantteja ja muokkaimia. Ehdokkaat, jotka eivät vastaa todellista apuluokkaa, hylätään.

Sarjoita ja optimoi. ast.php:n toCss() käy puun läpi (apufunktioilla kohteessa walk.php) ja tuottaa CSS-merkkijonon. lightningcss-vastineen muunnokset kohteessa _tailwindphp/LightningCss.php suoritetaan, jotta tulos vastaa sitä, mitä TailwindCSS tuottaa Rust-jälkikäsittelyvaiheen jälkeen.

Pienennä. Kun minify on käytössä, toCss() tuottaa sarjoituksen aikana pienennettyä CSS-koodia. _tailwindphp/CssMinifier.php toteuttaa erillisen tw::minify()-merkkijonovaiheen. Katso Välimuisti ja pienennys.

Lähdekoodin rakenne

src/ jäljittelee TailwindCSS:tä. Ainoa rakenteellinen muutos: TailwindCSS:n utilities.ts on yli 6,000 riviä pitkä, joten se on ylläpidettävyyden vuoksi jaettu kohteeseen src/utilities/, jossa on yksi tiedosto luokkaa kohden.

Koodi

src/
├── _tailwindphp/                # PHP-specific — NOT part of the TailwindCSS port
│   ├── LightningCss.php         # CSS transforms (lightningcss Rust library equivalent)
│   ├── CssMinifier.php          # CSS minification
│   └── lib/                     # Companion library ports (TailwindPHP\Lib\*)
│       ├── clsx/                # clsx port
│       ├── tailwind-merge/      # tailwind-merge port
│       └── cva/                 # CVA port
│
├── plugin/                      # Plugin system
│   └── plugins/
│       ├── typography-plugin.php  # @tailwindcss/typography port
│       └── forms-plugin.php       # @tailwindcss/forms port
│
├── utilities/                   # Split from TailwindCSS utilities.ts (one file per category)
│   ├── accessibility.php        # sr-only, forced-colors
│   ├── backgrounds.php          # bg-*, gradient-*, from-*, via-*, to-*
│   ├── borders.php              # border-*, rounded-*, divide-*, outline-*
│   ├── effects.php              # shadow-*, opacity-*, mix-blend-*
│   ├── filters.php              # blur-*, brightness-*, contrast-*, …
│   ├── flexbox.php              # flex-*, grid-*, gap-*, justify-*, align-*
│   ├── interactivity.php        # cursor-*, scroll-*, touch-*, select-*
│   ├── layout.php               # display, position, z-*, overflow-*, …
│   ├── masks.php                # mask-linear-*, mask-radial-*, mask-conic-*
│   ├── sizing.php               # w-*, h-*, min-*, max-*, size-*
│   ├── spacing.php              # m-*, p-*, space-*
│   ├── svg.php                  # fill-*, stroke-*
│   ├── tables.php               # border-collapse, table-layout
│   ├── transforms.php           # translate-*, rotate-*, scale-*, skew-*
│   ├── transitions.php          # transition-*, duration-*, ease-*, delay-*
│   └── typography.php           # font-*, text-*, leading-*, tracking-*
│
├── utils/                       # Helper functions (ported from utils/)
│
├── index.php                    # Main entry — compile(), cn(), variants(), merge(), join()
├── ast.php                      # AST nodes and toCss()
├── candidate.php                # Candidate parsing (class name → parts)
├── compile.php                  # Candidate to CSS compilation
├── css-functions.php            # theme(), --theme(), --spacing(), --alpha()
├── css-parser.php               # CSS parsing
├── design-system.php            # Central registry for utilities/variants
├── plugin.php                   # Plugin system (PluginInterface, PluginAPI, PluginManager)
├── theme.php                    # Theme value resolution
├── utilities.php                # Utility registration and lookup
├── value-parser.php             # CSS value parsing
├── variants.php                 # Variant handling (hover, focus, responsive, …)
└── walk.php                     # AST traversal

lightningcssin vastine

TailwindCSS siirtää CSS-jälkikäsittelynsä — sisäkkäiset säännöt, mediakyselyjen käsittelyn ja arvojen yksinkertaistamisen — lightningcss-ohjelmalle, joka on Rust-kielellä kirjoitettu jäsennin, muunnin ja pienentäjä. PHP ei voi ladata Rust-kirjastoa, joten src/_tailwindphp/LightningCss.php toteuttaa uudelleen ne muunnokset, joita TailwindPHP todella käyttää. Näin saadaan tavutasolla identtinen tulos niissä tapauksissa, jotka testisarja kattaa.

Vahvistettuihin muunnoksiin kuuluvat:

Muunnos	Mitä se tekee
Sisäkkäisyyden litistäminen	Ratkaisee `&`-valitsimet viitteen `:is(…)`-sääntöjen avulla ja litistää sisäkkäiset säännöt (`handleNesting()` kohteessa `ast.php`, siirros TailwindCSS-vaiheesta); `transformNesting` muuntaa ensimmäisen ilmoituksia sisältävän tason alle jäävän sisäkkäisyyden vanhempaa syntaksia käyttävään muotoon
Ehdollisten at-sääntöjen litistäminen	Litistää sisäkkäiset `@media`-, `@supports`-, `@container`- ja `@starting-style`-säännöt paikoilleen lähdejärjestyksen säilyttäen ja yhdistää vain suoraan vierekkäiset sisarukset, joilla on samat ehdot
Määritysten järjestäminen	Järjestää määritykset uudelleen lightningcssin määrityskäsittelijöiden ketjun mukaan, jotta ominaisuudet ovat viitteen mukaisessa järjestyksessä (`reorderDeclarations`)
`calc()`-yksinkertaistus	Yksinkertaistaa `calc()`-lausekkeita (`simplifyCalcExpressions`)
Alkunollien poistaminen	`0.5` → `.5` (`normalizeLeadingZeros`)
Muunnosfunktioiden välilyönnit	Yhtenäistää muunnosfunktioiden sisäiset välilyönnit (`normalizeTransformFunctions`)
Ruudukkoarvojen normalisointi	Lisää välilyönnit `/`-merkin ympärille span-arvoissa ja muuntaa paljaat kokonaisluvut px-arvoiksi kohteessa `grid-template-*` (`normalizeGridValues`)
Värien normalisointi	Yhtenäistää värien syntaksin ja laskee `color-mix()`-arvon muotoon `oklab()` (`normalizeColors`, `evaluateColorMix`)
URL-lainausmerkit	`url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`)
Valmistajakohtaiset etuliitteet	Autoprefixer-vastaavat etuliitteet (`addVendorPrefixes`)

Tämä tiedosto on tarkoituksella eristetty hakemistoon _tailwindphp/ ja merkitty tunnisteella @port-deviation:replacement — se edustaa ulkoista riippuvuutta sen sijaan, että TailwindCSS-lähdekoodi siirrettäisiin.

Siirroksen poikkeamamerkit

Jokaisen toteutustiedoston dokumentointilohkossa on @port-deviation:*-merkkejä, jotka kertovat, missä ja miksi PHP-toteutus poikkeaa alkuperäisestä TypeScript-versiosta. Näin PHP- ja TailwindCSS-lähdekoodia vertailevan lukijan ei tarvitse arvailla, onko ero tarkoituksellinen.

Merkki	Merkitys
`@port-deviation:none`	Suora 1:1-siirros, jossa ei ole merkittäviä poikkeamia
`@port-deviation:async`	PHP käyttää synkronista koodia async/await-rakenteen sijaan
`@port-deviation:storage`	Tietorakenteet eroavat (PHP-taulukko vastaan JS-Map/Set)
`@port-deviation:types`	PHPDoc-merkinnät tyyppien TypeScript sijaan
`@port-deviation:sourcemaps`	Lähdekartan seuranta jätetty pois
`@port-deviation:enum`	PHP-vakiot TypeScript-enumien sijaan
`@port-deviation:errors`	Erilainen virheenkäsittelytapa
`@port-deviation:replacement`	PHP-toteutus korvaa ulkoisen kirjaston (e.g. lightningcss)
`@port-deviation:helper`	PHP-kohtainen apufunktio, jota alkuperäisessä ei ole
`@port-deviation:performance`	PHP-kohtainen optimointi, joka säilyttää saman tulosteen
`@port-deviation:omitted`	Koko moduulia tai ominaisuutta ei ole siirretty (ei kuulu laajuuteen)

Katso @port-deviation:performance-merkkien ja vastaavuuden valvonnan kuvaus kohdasta Suorituskyky ja testaus.