Arhitektuur

Vaata Markdownina Muuda teenuses GitHub Dokumentatsioon: 3843abd

TailwindPHP on 1:1 port. Koodibaas peegeldab TailwindCSS enda struktuuri — samad failinimed, sama korraldus — ja eraldab kataloogi src/_tailwindphp/ need osad, mida ei saa otse portida (PHP-il pole Rust ega V8). Sellel lehel käsitletakse kompileerimistoru, lähtekoodi paigutust, lightningcss taasloomist ja kõrvalekallete dokumenteerimise tava.

Töötlusahel

CSS loomine koosneb etappidest. Eraldi ehitusetappi pole – iga tw::generate() kutse käivitab kogu töövoo.

Kood

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

Parsimine. css-parser.php loeb sisendiks antud CSS-i – @import, @theme, @utility, @layer ja toorreeglid – ning loob abstraktse süntaksipuu, mis koosneb ast.php sõlmedest (stiilireeglid, at-reeglid ja deklaratsioonid). Selles etapis lahendatakse ja asendatakse virtuaalmoodulite @import direktiivid (tailwindcss, tailwindcss/preflight, …) ning failiteed.

Disainisüsteemi loomine. theme.php lahendab teemaväärtused (värvid, vahed ja murdepunktid) parsitud @theme plokkide ja vaikeväärtuste põhjal. design-system.php on keskne register, mis seob teema utiliitide ja variantide otsingutega, mis on määratletud failides utilities.php ja variants.php.

Sisu skannimine. candidate.php eraldab etteantud sisust (HTML, mallid) võimalike klassinimede kandidaadid ja parsib igaühe osadeks: põhiutiliit, variandid, muutjad, suvalised väärtused ja olulisuse lipp.

Kompileerimine. compile.php teisendab iga kandidaadi AST-sõlmedeks, otsides selle disainisüsteemist ning rakendades variante ja muutjaid. Kandidaadid, mis ei vasta ühelegi päriselt olemasolevale utiliidile, jäetakse kõrvale.

Serialiseerimine ja optimeerimine. ast.php toCss() läbib puu (abifunktsioonid asuvad failis walk.php) ja väljastab CSS-stringi. Rakendatakse lightningcss-iga samaväärseid teisendusi kataloogis _tailwindphp/LightningCss.php, et väljund vastaks sellele, mida TailwindCSS toodab pärast Rust järeltöötlusetappi.

Vähendamine. Kui minify on lubatud, väljastab toCss() serialiseerimise ajal vähendatud CSS-i. Eraldiseisvat tw::minify()-stringi etappi toetab _tailwindphp/CssMinifier.php. Vt Vahemällu salvestamine ja vähendamine.

Lähtekoodi paigutus

src/ järgib TailwindCSS ülesehitust. Ainus struktuurimuudatus: TailwindCSS failis utilities.ts on üle 6,000 rea, seega on see hooldatavuse huvides jagatud kategooriate kaupa failideks src/utilities/.

Kood

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

lightningcss-i samaväärne teostus

TailwindCSS delegeerib oma CSS järeltöötluse – pesastamise, meediapäringute käsitlemise ja väärtuste lihtsustamise – teegile lightningcss, mis on keeles Rust kirjutatud parser, teisendaja ja vähendaja. PHP ei saa laadida Rust teeki, seega taasloob src/_tailwindphp/LightningCss.php teisendused, millele TailwindPHP tegelikult toetub, ning väljastab testikomplektiga kaetud juhtudel baiditäpselt sama tulemuse.

Kinnitatud teisendused hõlmavad järgmist:

Teisendus	Mida see teeb
Pesastuse tasandamine	Lahendab `&` selektorid viite `:is(…)` reeglitega ja tasandab pesastatud reeglid (`handleNesting()` failis `ast.php`, TailwindCSS läbimise port); `transformNesting` alandab esimese deklaratsioone sisaldava taseme alla jääva pesastuse
Tingimuslike at-reeglite tasandamine	Tasandab pesastatud `@media`, `@supports`, `@container` ja `@starting-style` oma asukohas, säilitades lähtekoodi järjekorra, ning ühendab ainult vahetult kõrvuti asuvad identsete tingimustega õedreeglid
Deklaratsioonide järjestamine	Järjestab deklaratsioonid lightningcss-i deklaratsioonikäsitlejate ahela järgi, et omadused ilmuksid viitega samas järjekorras (`reorderDeclarations`)
`calc()` lihtsustamine	Lihtsustab `calc()` avaldisi (`simplifyCalcExpressions`)
Eesoleva nulli eemaldamine	`0.5` → `.5` (`normalizeLeadingZeros`)
Teisendusfunktsioonide tühikud	Normaliseerib tühikud teisendusfunktsioonides (`normalizeTransformFunctions`)
Ruudustikuväärtuste normaliseerimine	Lisab span-väärtustes `/` ümber tühikud, muudab paljad täisarvud px-ühikusse `grid-template-*` jaoks (`normalizeGridValues`)
Värvide normaliseerimine	Normaliseerib värvisüntaksi ja arvutab `color-mix()` väärtuseks `oklab()` (`normalizeColors`, `evaluateColorMix`)
URL jutumärgid	`url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`)
Tootjaprefiksid	Autoprefixer-iga samaväärne prefiksite lisamine (`addVendorPrefixes`)

See fail on tahtlikult paigutatud eraldatult kataloogi _tailwindphp/ ja märgitud @port-deviation:replacement — see tähistab välist sõltuvust, mitte TailwindCSS lähtekoodi porti.

Pordierinevuste markerid

Iga teostusfaili dokumendiplokis on @port-deviation:* markerid, mis selgitavad, kus ja miks PHP teostus erineb TypeScript algsest. Eesmärk on, et lugeja ei peaks PHP ja TailwindCSS lähtekoodi võrreldes kunagi mõtlema, kas erinevus on tahtlik.

Marker	Tähendus
`@port-deviation:none`	Otsene 1:1 port ilma oluliste erinevusteta
`@port-deviation:async`	PHP kasutab async/await asemel sünkroonset koodi
`@port-deviation:storage`	Erinevad andmestruktuurid (PHP massiiv võrreldes JS Map/Set-iga)
`@port-deviation:types`	TypeScript tüüpide asemel PHPDoc-i annotatsioonid
`@port-deviation:sourcemaps`	Lähtekaardi jälgimine on välja jäetud
`@port-deviation:enum`	PHP konstandid TypeScript enumite asemel
`@port-deviation:errors`	Teistsugune vigade käsitlemise viis
`@port-deviation:replacement`	PHP teostus asendab välise teegi (e.g. lightningcss)
`@port-deviation:helper`	Ainult PHP jaoks mõeldud abifunktsioon, mida algses versioonis pole
`@port-deviation:performance`	Ainult PHP jaoks mõeldud optimeerimine, mis säilitab identse väljundi
`@port-deviation:omitted`	Kogu moodul või funktsioon pole porditud (ei kuulu töö ulatusse)

@port-deviation:performance markerite ja paarsuse tagamise kohta leiate teavet jaotisest Jõudlus ja testimine.