Architektūra

Peržiūrėti kaip Markdown Redaguoti per GitHub Dokumentacija: 3843abd

TailwindPHP yra tikslus 1:1 perkėlimas. Kodų bazė atkartoja pačios TailwindCSS struktūrą – tie patys failų pavadinimai ir išdėstymas. Dalys, kurių neįmanoma tiesiogiai perkelti (PHP neturi Rust ar V8), atskirtos į src/_tailwindphp/. Šiame puslapyje aprašomi kompiliavimo konvejeris, šaltinio kodų išdėstymas, lightningcss realizacija ir nukrypimų dokumentavimo tvarka.

Proceso eiga

CSS generavimas vyksta keliais etapais. Atskiro kūrimo žingsnio nėra – kiekvienas tw::generate() iškvietimas vykdo visą konvejerį.

Kodas

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

Analizavimas. css-parser.php analizuoja CSS įvestį – @import, @theme, @utility, @layer ir neapdorotas taisykles – į ast.php mazgų abstrakčią sintaksės medį (stiliaus taisykles, at taisykles ir deklaracijas). Šiame etape išsprendžiamos ir pakeičiamos @import direktyvos, skirtos virtualiems moduliams (tailwindcss, tailwindcss/preflight, …), bei failų keliai.

Dizaino sistemos kūrimas. theme.php išanalizuotuose @theme blokuose ir numatytosiose reikšmėse suranda temos reikšmes (spalvas, tarpus, lūžio taškus). design-system.php yra centrinis registras, susiejantis temą su utilities.php ir variants.php apibrėžtomis utilitų bei variantų paieškomis.

Turinio nuskaitymas. candidate.php pateiktame turinyje (HTML, šablonuose) aptinka galimus klasių pavadinimus ir išskaido kiekvieną į dalis: bazinį utilitą, variantus, modifikatorius, savavališkas reikšmes ir svarbos žymą.

Kompiliavimas. compile.php kiekvieną galimą kandidatą paverčia AST mazgais, ieškodama jo dizaino sistemoje ir pritaikydama variantus bei modifikatorius. Kandidatai, neatitinkantys realaus utilito, atmetami.

Serializavimas ir optimizavimas. ast.php toCss() pereina medį (naudodama pagalbines funkcijas iš walk.php) ir išveda CSS eilutę. Taikomos _tailwindphp/LightningCss.php esančios transformacijos, atitinkančios lightningcss, kad išvestis sutaptų su ta, kurią TailwindCSS sukuria po Rust papildomo apdorojimo etapo.

Minifikavimas. Įjungus minify, toCss() serializavimo metu išveda minifikuotą CSS. Savarankišką tw::minify() eilutės apdorojimą atlieka _tailwindphp/CssMinifier.php. Žr. Spartinimas talpykloje ir minifikavimas.

Šaltinio kodo išdėstymas

src/ atkartoja TailwindCSS. Vienintelis struktūrinis pakeitimas: TailwindCSS utilities.ts yra 6,000+ eilučių, todėl priežiūros patogumui jis suskaidytas į src/utilities/ – po vieną failą kiekvienai kategorijai.

Kodas

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 atitikmuo

TailwindCSS CSS papildomą apdorojimą – įdėjimą, medijos užklausų tvarkymą ir reikšmių supaprastinimą – patiki lightningcss, analizatoriui, transformatoriui ir minifikatoriui, parašytam Rust kalba. PHP negali įkelti Rust bibliotekos, todėl src/_tailwindphp/LightningCss.php iš naujo realizuoja transformacijas, kuriomis iš tiesų remiasi TailwindPHP; testų rinkinio aprėpiamais atvejais išvestis sutampa baitas į baitą.

Patvirtintos transformacijos:

Transformacija	Ką ji daro
Įdėjimo išskleidimas	Išsprendžia `&` selektorius pagal nuorodos `:is(…)` taisykles ir išskleidžia įdėtines taisykles (`handleNesting()` faile `ast.php`, TailwindCSS etapo perkėlimas); `transformNesting` išskleidžia po pirmojo deklaracijas turinčio lygmens likusį įdėjimą
Sąlyginių at taisyklių išskleidimas	Vietoje išskleidžia įdėtines `@media`, `@supports`, `@container` ir `@starting-style`, išlaikydamas pradinę tvarką; sujungiami tik tiesiogiai greta esantys vienodų sąlygų elementai
Deklaracijų tvarka	Deklaracijos perrikiuojamos pagal lightningcss deklaracijų tvarkyklės grandinę, todėl savybės išvedamos tokia tvarka kaip nuorodoje (`reorderDeclarations`)
`calc()` supaprastinimas	Supaprastinamos `calc()` išraiškos (`simplifyCalcExpressions`)
Nulių pradžioje šalinimas	`0.5` → `.5` (`normalizeLeadingZeros`)
Tarpai transformavimo funkcijose	Normalizuojami tarpai transformavimo funkcijų viduje (`normalizeTransformFunctions`)
Tinklelio reikšmių normalizavimas	Tarp reikšmių su `/` pridedami tarpai, o sveikieji skaičiai be vienetų paverčiami px, kai naudojamas `grid-template-*` (`normalizeGridValues`)
Spalvų normalizavimas	Normalizuojama spalvų sintaksė, o `color-mix()` apskaičiuojama į `oklab()` (`normalizeColors`, `evaluateColorMix`)
URL kabutės	`url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`)
Tiekėjo prefiksai	Autoprefixer atitinkantis prefiksų pridėjimas (`addVendorPrefixes`)

Šis failas sąmoningai laikomas _tailwindphp/ ir pažymėtas @port-deviation:replacement – jis atstoja išorinę priklausomybę, o ne perkelia TailwindCSS šaltinio kodą.

Perkėlimo nukrypimų žymos

Kiekvieno realizacijos failo dokumentacijos bloke yra @port-deviation:* žymos, nurodančios, kur ir kodėl PHP realizacija skiriasi nuo pradinės TypeScript versijos. Lyginant PHP su TailwindCSS šaltinio kodu, neturi kilti abejonių, ar skirtumas atsirado tyčia.

Žyma	Reikšmė
`@port-deviation:none`	Tiesioginis 1:1 perkėlimas be reikšmingų nukrypimų
`@port-deviation:async`	PHP vietoj async/await naudoja sinchroninį kodą
`@port-deviation:storage`	Skirtingos duomenų struktūros (PHP masyvas, o JS Map/Set)
`@port-deviation:types`	Vietoj TypeScript tipų naudojamos PHPDoc anotacijos
`@port-deviation:sourcemaps`	Šaltinio žemėlapio sekimas praleistas
`@port-deviation:enum`	Vietoj TypeScript išvardijimų naudojamos PHP konstantos
`@port-deviation:errors`	Kitoks klaidų tvarkymo būdas
`@port-deviation:replacement`	PHP realizacija pakeičia išorinę biblioteką (e.g. lightningcss)
`@port-deviation:helper`	Tik PHP skirtas pagalbinis įrankis, kurio nėra pradinėje versijoje
`@port-deviation:performance`	Tik PHP skirta optimizacija, išlaikanti identišką išvestį
`@port-deviation:omitted`	Visas modulis arba funkcija neperkelta (nepatenka į apimtį)

Apie @port-deviation:performance žymas ir pariteto užtikrinimą skaitykite skiltyje Našumas ir testavimas.