Αρχιτεκτονική

Προβολή ως Markdown Επεξεργασία στο GitHub Τεκμηρίωση στο 3843abd

Το TailwindPHP είναι μεταφορά 1:1. Η βάση κώδικα αντικατοπτρίζει τη δομή του ίδιου του TailwindCSS — ίδια ονόματα αρχείων, ίδια οργάνωση — και απομονώνει στο src/_tailwindphp/ τα μέρη που δεν μπορούν να μεταφερθούν άμεσα (το PHP δεν διαθέτει Rust ούτε V8). Σε αυτή τη σελίδα περιγράφονται η διαδικασία μεταγλώττισης, η διάταξη του πηγαίου κώδικα, η επανυλοποίηση του lightningcss και η σύμβαση τεκμηρίωσης των αποκλίσεων.

Η ροή επεξεργασίας

Η δημιουργία του CSS περιλαμβάνει διαδοχικά στάδια. Δεν υπάρχει ξεχωριστό βήμα κατασκευής — κάθε κλήση του tw::generate() εκτελεί ολόκληρη τη διαδικασία.

Κώδικας

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

Ανάλυση. Το css-parser.php διαβάζει την είσοδο CSS — @import, @theme, @utility, @layer, ακατέργαστους κανόνες — σε ένα αφηρημένο συντακτικό δέντρο από κόμβους ast.php (κανόνες στυλ, at-rules, δηλώσεις). Οι οδηγίες @import για εικονικές μονάδες (tailwindcss, tailwindcss/preflight, …) και οι διαδρομές αρχείων επιλύονται και αντικαθίστανται σε αυτό το στάδιο.

Δημιουργία συστήματος σχεδίασης. Το theme.php επιλύει τις τιμές θέματος (χρώματα, αποστάσεις, σημεία διακοπής) από τα μπλοκ @theme που αναλύθηκαν και τις προεπιλογές. Το design-system.php είναι το κεντρικό μητρώο που συνδέει το θέμα με τις αναζητήσεις βοηθητικών κλάσεων και παραλλαγών που ορίζονται στα utilities.php και variants.php.

Σάρωση περιεχομένου. Το candidate.php εξάγει υποψήφια ονόματα κλάσεων από το παρεχόμενο περιεχόμενο (HTML, πρότυπα) και αναλύει καθένα στα μέρη του — βασική βοηθητική κλάση, παραλλαγές, τροποποιητές, αυθαίρετες τιμές και σημαία σημαντικότητας.

Μεταγλώττιση. Το compile.php μετατρέπει κάθε υποψήφιο σε κόμβους AST, αναζητώντας τον στο σύστημα σχεδίασης και εφαρμόζοντας τις παραλλαγές και τους τροποποιητές του. Οι υποψήφιοι που δεν αντιστοιχούν σε πραγματική βοηθητική κλάση απορρίπτονται.

Σειριοποίηση και βελτιστοποίηση. Το toCss() του ast.php διατρέχει το δέντρο (βοηθητικές συναρτήσεις στο walk.php) και παράγει τη συμβολοσειρά CSS. Εφαρμόζονται οι μετασχηματισμοί στο _tailwindphp/LightningCss.php που αντιστοιχούν στο lightningcss, ώστε η έξοδος να ταιριάζει με εκείνη που παράγει το TailwindCSS μετά το στάδιο μετεπεξεργασίας του Rust.

Ελαχιστοποίηση. Όταν είναι ενεργοποιημένο το minify, το toCss() παράγει ελαχιστοποιημένο CSS κατά τη σειριοποίηση. Το _tailwindphp/CssMinifier.php υποστηρίζει το αυτόνομο πέρασμα συμβολοσειράς tw::minify(). Δείτε την ενότητα Προσωρινή αποθήκευση και ελαχιστοποίηση.

Διάταξη πηγαίου κώδικα

Το src/ αντικατοπτρίζει το TailwindCSS. Η μία δομική αλλαγή: το utilities.ts του TailwindCSS έχει πάνω από 6,000 γραμμές, γι' αυτό χωρίζεται σε src/utilities/ με ένα αρχείο ανά κατηγορία για ευκολότερη συντήρηση.

Κώδικας

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

Το TailwindCSS αναθέτει τη μετεπεξεργασία CSS — ένθεση, διαχείριση ερωτημάτων μέσων, απλοποίηση τιμών — στο lightningcss, έναν αναλυτή/μετασχηματιστή/ελαχιστοποιητή γραμμένο σε Rust. Το PHP δεν μπορεί να φορτώσει βιβλιοθήκη Rust, γι' αυτό το src/_tailwindphp/LightningCss.php επανυλοποιεί τους μετασχηματισμούς στους οποίους βασίζεται στην πράξη το TailwindPHP, παράγοντας έξοδο ταυτόσημη σε επίπεδο byte για τις περιπτώσεις που καλύπτει η σουίτα δοκιμών.

Οι επιβεβαιωμένοι μετασχηματισμοί περιλαμβάνουν:

Μετασχηματισμός	Τι κάνει
Ισοπέδωση ένθετων κανόνων	Επιλύει τους επιλογείς `&` με τους κανόνες `:is(…)` της αναφοράς και ισοπεδώνει τους ένθετους κανόνες (`handleNesting()` στο `ast.php`, μεταφορά του περάσματος TailwindCSS)· το `transformNesting` υποβιβάζει επίπεδο ένθεσης στους κανόνες που απομένουν κάτω από το πρώτο επίπεδο που περιέχει δηλώσεις
Ισοπέδωση υπό συνθήκη κανόνων at-rule	Ισοπεδώνει επιτόπου ένθετα `@media`, `@supports`, `@container` και `@starting-style`, διατηρώντας τη σειρά του πηγαίου κώδικα, και συγχωνεύει μόνο άμεσα γειτονικά αδέλφια με πανομοιότυπες συνθήκες
Ταξινόμηση δηλώσεων	Αναδιατάσσει τις δηλώσεις σύμφωνα με την αλυσίδα χειριστών δηλώσεων του lightningcss, ώστε οι ιδιότητες να εμφανίζονται με τη σειρά της αναφοράς (`reorderDeclarations`)
Απλοποίηση `calc()`	Απλοποιεί εκφράσεις `calc()` (`simplifyCalcExpressions`)
Αφαίρεση αρχικού μηδενικού	`0.5` → `.5` (`normalizeLeadingZeros`)
Κενά στις συναρτήσεις μετασχηματισμού	Κανονικοποιεί τα κενά μέσα στις συναρτήσεις μετασχηματισμού (`normalizeTransformFunctions`)
Κανονικοποίηση τιμών πλέγματος	Προσθέτει κενά γύρω από το `/` σε τιμές span, ακέραιοι χωρίς μονάδα → px για το `grid-template-*` (`normalizeGridValues`)
Κανονικοποίηση χρωμάτων	Κανονικοποιεί τη σύνταξη χρωμάτων και υπολογίζει το `color-mix()` σε `oklab()` (`normalizeColors`, `evaluateColorMix`)
Κανονικοποίηση εισαγωγικών URL	`url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`)
Προθέματα προμηθευτών	Προσθήκη προθεμάτων ισοδύναμη με το Autoprefixer (`addVendorPrefixes`)

Αυτό το αρχείο έχει απομονωθεί σκόπιμα στο _tailwindphp/ και επισημανθεί ως @port-deviation:replacement — αποτελεί υποκατάστατο εξωτερικής εξάρτησης και όχι μεταφορά του πηγαίου κώδικα TailwindCSS.

Δείκτες αποκλίσεων της μεταφοράς

Κάθε αρχείο υλοποίησης φέρει δείκτες @port-deviation:* στο docblock του, οι οποίοι δηλώνουν πού και γιατί η υλοποίηση PHP αποκλίνει από το αρχικό TypeScript. Στόχος είναι ο αναγνώστης που συγκρίνει το PHP με τον πηγαίο κώδικα TailwindCSS να μη χρειάζεται ποτέ να αναρωτηθεί αν μια διαφορά είναι σκόπιμη.

Δείκτης	Σημασία
`@port-deviation:none`	Άμεση μεταφορά 1:1 χωρίς σημαντικές αποκλίσεις
`@port-deviation:async`	Το PHP χρησιμοποιεί σύγχρονο κώδικα αντί για async/await
`@port-deviation:storage`	Διαφορετικές δομές δεδομένων (πίνακας PHP αντί για Map/Set JS)
`@port-deviation:types`	Σχόλια PHPDoc αντί για τύπους TypeScript
`@port-deviation:sourcemaps`	Η παρακολούθηση source map παραλείπεται
`@port-deviation:enum`	Σταθερές PHP αντί για enum TypeScript
`@port-deviation:errors`	Διαφορετική προσέγγιση στη διαχείριση σφαλμάτων
`@port-deviation:replacement`	Υλοποίηση PHP που αντικαθιστά εξωτερική βιβλιοθήκη (e.g. lightningcss)
`@port-deviation:helper`	Βοηθητικό στοιχείο ειδικό για το PHP, που δεν υπάρχει στο αρχικό
`@port-deviation:performance`	Βελτιστοποίηση ειδική για το PHP που διατηρεί πανομοιότυπη έξοδο
`@port-deviation:omitted`	Δεν έχει μεταφερθεί ολόκληρη ενότητα/λειτουργία (εκτός πεδίου εφαρμογής)

Για τους δείκτες @port-deviation:performance και τον τρόπο επιβολής της ισοτιμίας, δείτε την ενότητα Απόδοση & δοκιμές.