Arhitektūra

Skatīt kā Markdown Rediģēt vietnē GitHub Dokumentācija vietnē 3843abd

TailwindPHP ir 1:1 ports. Koda bāze atspoguļo paša TailwindCSS struktūru — tie paši failu nosaukumi, tā pati organizācija — un nodala daļas, kuras nevar tieši pārnest (PHP nav Rust, nav V8), zem src/_tailwindphp/. Šajā lapā aplūkots kompilācijas konveijers, avota izkārtojums, lightningcss atkārtota ieviešana un konvencija, ko izmanto atšķirību dokumentēšanai.

Darbplūsma

CSS ģenerēšana notiek vairākos posmos. Atsevišķa būvēšanas soļa nav — katrs tw::generate() izsaukums izpilda visu konveijeru.

Kods

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

Parsēšana. css-parser.php nolasa CSS ievadi — @import, @theme, @utility, @layer, neapstrādātus noteikumus — un izveido abstraktu sintakses koku no ast.php mezgliem (stila noteikumi, at-rule direktīvas, deklarācijas). Šajā posmā tiek atrisinātas un aizstātas @import direktīvas virtuālajiem moduļiem (tailwindcss, tailwindcss/preflight, …) un failu ceļi.

Dizaina sistēmas izveide. theme.php atrisina tēmas vērtības (krāsas, atstarpes, pārtraukuma punkti), izmantojot parsētos @theme blokus un noklusējuma vērtības. design-system.php ir centrālais reģistrs, kas sasaista tēmu ar utilītu un variantu meklēšanu, kas definēta utilities.php un variants.php.

Satura skenēšana. candidate.php izvelk klašu nosaukumu kandidātus no norādītā satura (HTML, veidnes) un sadala katru tā sastāvdaļās — bāzes utilīta, varianti, modifikatori, patvaļīgas vērtības, svarīguma karodziņš.

Kompilēšana. compile.php pārvērš katru kandidātu AST mezglos, meklējot to dizaina sistēmā un piemērojot tā variantus un modifikatorus. Kandidāti, kurus nevar atrisināt kā īstas utilītas, tiek atmesti.

Serializēšana un optimizēšana. ast.php toCss() šķērso koku (palīgfunkcijas atrodas walk.php) un izvada CSS virkni. Tiek piemērotas _tailwindphp/LightningCss.php transformācijas, kas ir ekvivalentas lightningcss, lai izvade atbilstu tam, ko izveido TailwindCSS pēc sava Rust pēcapstrādes posma.

Minificēšana. Ja minify ir iespējots, toCss() serializēšanas laikā izvada minificētu CSS. _tailwindphp/CssMinifier.php nodrošina atsevišķo tw::minify() virknes apstrādi. Skatiet Kešatmiņa un minificēšana.

Avota izkārtojums

src/ atspoguļo TailwindCSS. Vienīgā strukturālā izmaiņa: TailwindCSS utilities.ts ir 6,000+ rindu gara, tāpēc tā uzturēšanas ērtībai sadalīta src/utilities/, katrai kategorijai izveidojot atsevišķu failu.

Kods

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 ekvivalents

TailwindCSS deleģē savu CSS pēcapstrādi — ligzdošanu, multivides vaicājumu apstrādi, vērtību vienkāršošanu — lightningcss — parserim, transformētājam un minificētājam, kas rakstīts Rust. PHP nevar ielādēt Rust bibliotēku, tāpēc src/_tailwindphp/LightningCss.php atkārtoti ievieš transformācijas, uz kurām faktiski paļaujas TailwindPHP, radot baitu līmenī identisku izvadi gadījumos, ko aptver testu kopa.

Apstiprinātās transformācijas ietver:

Transformācija	Ko tā dara
Ligzdošanas saplacināšana	Atrisina `&` atlasītājus, izmantojot atsauces `:is(…)` noteikumus, un saplacina ligzdotos noteikumus (`handleNesting()` failā `ast.php`, TailwindCSS posma ports); `transformNesting` pazemina atlikušās ligzdošanas līmeni zem pirmā deklarācijas līmeņa
Nosacījumu at-rule direktīvu saplacināšana	Saplacina ligzdotās `@media`, `@supports`, `@container` un `@starting-style` vietā, saglabājot avota secību, un apvieno tikai tieši blakus esošus elementus ar identiskiem nosacījumiem
Deklarāciju secība	Pārkārto deklarācijas atbilstoši lightningcss deklarāciju apstrādes ķēdei, lai rekvizīti izvadē būtu atsauces secībā (`reorderDeclarations`)
`calc()` vienkāršošana	Vienkāršo `calc()` izteiksmes (`simplifyCalcExpressions`)
Sākuma nulles noņemšana	`0.5` → `.5` (`normalizeLeadingZeros`)
Atstarpes transformācijas funkcijās	Normalizē atstarpes transformācijas funkcijās (`normalizeTransformFunctions`)
Režģa vērtību normalizēšana	Pievieno atstarpes ap `/` span vērtībās, veselus skaitļus bez vienībām pārvērš par px, ja izmantots `grid-template-*` (`normalizeGridValues`)
Krāsu normalizēšana	Normalizē krāsu sintaksi un aprēķina `color-mix()` līdz `oklab()` (`normalizeColors`, `evaluateColorMix`)
URL pēdiņas	`url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`)
Piegādātāju prefiksi	Autoprefixer ekvivalenta prefiksu pievienošana (`addVendorPrefixes`)

Šis fails apzināti ievietots karantīnā zem _tailwindphp/ un marķēts kā @port-deviation:replacement — tas aizstāj ārēju atkarību, nevis pārnes TailwindCSS pirmkodu.

Porta atšķirību marķieri

Katrā realizācijas failā docblock komentārā ir @port-deviation:* marķieri, kas norāda, kur un kāpēc PHP realizācija atšķiras no sākotnējās TypeScript versijas. Mērķis ir panākt, lai, salīdzinot PHP ar TailwindCSS pirmkodu, lasītājam nebūtu jāmin, vai atšķirība ir apzināta.

Marķieris	Nozīme
`@port-deviation:none`	Tiešs 1:1 ports bez būtiskām atšķirībām
`@port-deviation:async`	PHP izmanto sinhrono kodu async/await vietā
`@port-deviation:storage`	Atšķirīgas datu struktūras (PHP masīvs, nevis JS Map/Set)
`@port-deviation:types`	PHPDoc anotācijas TypeScript tipu vietā
`@port-deviation:sourcemaps`	Avota kartes izsekošana izlaista
`@port-deviation:enum`	PHP konstantes TypeScript uzskaitījumu vietā
`@port-deviation:errors`	Atšķirīga kļūdu apstrādes pieeja
`@port-deviation:replacement`	PHP realizācija, kas aizstāj ārēju bibliotēku (e.g. lightningcss)
`@port-deviation:helper`	PHP specifisks palīgrīks, kura nav oriģinālā
`@port-deviation:performance`	PHP specifiska optimizācija, kas saglabā identisku izvadi
`@port-deviation:omitted`	Viss modulis/funkcionalitāte nav pārnesta (ārpus tvēruma)

Informāciju par @port-deviation:performance marķieriem un to, kā tiek nodrošināta atbilstība, skatiet Veiktspēja un testēšana.