Mimari

Markdown olarak görüntüle GitHub üzerinde düzenle Dokümantasyon: 3843abd

TailwindPHP bir 1:1 uyarlamasıdır. Kod tabanı, TailwindCSS'ın kendi yapısını (aynı dosya adları ve aynı düzenleme) izler; doğrudan uyarlanması mümkün olmayan kısımları (PHP'te Rust ve V8 yoktur) src/_tailwindphp/ altında ayrı tutar. Bu sayfada derleme hattı, kaynak düzeni, lightningcss uygulaması ve farklılıkları belgeleme yaklaşımı anlatılır.

İşlem hattı

CSS üretimi bir aşamalar dizisinden oluşur. Ayrı bir derleme adımı yoktur; tw::generate() için yapılan her çağrı tüm hattı çalıştırır.

Kod

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

Ayrıştırma. css-parser.php, CSS girdisini — @import, @theme, @utility, @layer ve ham kuralları — ast.php düğümlerinden oluşan bir soyut sözdizimi ağacına (stil kuralları, at kuralları, bildirimler) dönüştürür. Sanal modüller (tailwindcss, tailwindcss/preflight, …) için @import yönergeleri ve dosya yolları bu aşamada çözümlenip yerine konur.

Tasarım sistemini oluşturma. theme.php, ayrıştırılmış @theme bloklarından ve varsayılanlardan tema değerlerini (renkler, boşluklar, kesme noktaları) çözümler. design-system.php, temayı utilities.php ve variants.php içinde tanımlanan yardımcı sınıf ve varyant aramalarıyla ilişkilendiren merkezi kayıt defteridir.

İçeriği tarama. candidate.php, sağlanan içerikten (HTML, şablonlar) sınıf adı adaylarını çıkarır ve her birini bileşenlerine ayırır: temel yardımcı sınıf, varyantlar, değiştiriciler, keyfî değerler ve important işareti.

Derleme. compile.php, her adayı tasarım sisteminde arayıp varyantlarını ve değiştiricilerini uygulayarak AST düğümlerine dönüştürür. Gerçek bir yardımcı sınıfa karşılık gelmeyen adaylar atılır.

Serileştirme ve optimizasyon. ast.php öğesinin toCss() bileşeni ağacı dolaşır (walk.php içindeki yardımcılarla) ve CSS dizgesini üretir. Çıktının, TailwindCSS tarafından Rust son işleme aşamasından sonra üretilenle eşleşmesi için _tailwindphp/LightningCss.php içindeki lightningcss eşdeğeri dönüşümler uygulanır.

Küçültme. minify etkinleştirildiğinde toCss(), serileştirme sırasında küçültülmüş CSS üretir. Bağımsız tw::minify() dize aşamasını _tailwindphp/CssMinifier.php sağlar. Bkz. Önbelleğe alma ve küçültme.

Kaynak düzeni

src/, TailwindCSS yapısını yansıtır. Tek yapısal değişiklik şu: TailwindCSS öğesinin utilities.ts bölümü 6,000 satırı aştığından, sürdürülebilirlik için her kategoriye bir dosya düşecek şekilde src/utilities/ dosyasına ayrılmıştır.

Kod

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 karşılığı

TailwindCSS, iç içe yerleştirme, medya sorgusu işleme ve değer basitleştirme gibi CSS son işleme görevlerini lightningcss'e devreder; bu, Rust ile yazılmış bir ayrıştırıcı/dönüştürücü/küçültücüdür. PHP, Rust kitaplığını yükleyemediğinden, src/_tailwindphp/LightningCss.php, TailwindPHP'in gerçekten kullandığı dönüşümleri yeniden uygular ve test paketinin kapsadığı durumlarda bayt bayt aynı çıktıyı üretir.

Doğrulanan dönüşümler şunlardır:

Dönüşüm	Yaptığı iş
İç içe yerleştirmeyi düzleştirme	`ast.php` içindeki başvuru `:is(…)` kurallarına göre `&` seçicilerini çözümler ve iç içe kuralları düzleştirir (TailwindCSS geçişinin bir uyarlaması olan `handleNesting()`); `transformNesting`, bildirim taşıyan ilk düzeyin altında kalan iç içe yerleştirmeyi alt düzeylere dönüştürür
Koşullu at kurallarını düzleştirme	İç içe `@media`, `@supports`, `@container` ve `@starting-style` kurallarını kaynak sırasını koruyarak yerinde düzleştirir ve yalnızca koşulları aynı olan, doğrudan bitişik kardeşleri birleştirir
Bildirim sıralaması	Özelliklerin başvurudaki sırayla çıkması için bildirimleri lightningcss bildirim işleyicisi zincirine göre yeniden sıralar (`reorderDeclarations`)
`calc()` basitleştirmesi	`calc()` ifadelerini basitleştirir (`simplifyCalcExpressions`)
Baştaki sıfırı kaldırma	`0.5` → `.5` (`normalizeLeadingZeros`)
Dönüştürme işlevlerinde boşluk	Dönüştürme işlevlerinin içindeki boşlukları normalleştirir (`normalizeTransformFunctions`)
Grid değerlerini normalleştirme	Aralık değerlerindeki `/` çevresine boşluk ekler; `grid-template-*` için yalın tamsayıları px'e dönüştürür (`normalizeGridValues`)
Renkleri normalleştirme	Renk söz dizimini normalleştirir ve `color-mix()` değerini `oklab()` olarak değerlendirir (`normalizeColors`, `evaluateColorMix`)
URL tırnaklama	`url(./x.jpg)` → `url("./x.jpg")` (`normalizeUrlQuoting`)
Üretici önekleri	Autoprefixer eşdeğeri önek ekleme (`addVendorPrefixes`)

Bu dosya bilerek _tailwindphp/ altında karantinaya alınmış ve @port-deviation:replacement olarak işaretlenmiştir — TailwindCSS kaynak kodunu uyarlamak yerine harici bir bağımlılığı temsil eder.

Uyarlama sapması işaretleri

Her uygulama dosyasının belge bloğunda, PHP uygulamasının TypeScript özgün sürümünden nerede ve neden ayrıldığını belirten @port-deviation:* işaretleri bulunur. Amaç, PHP ile TailwindCSS kaynak kodunu karşılaştıran okuyucunun bir farkın kasıtlı olup olmadığını sorgulamak zorunda kalmamasıdır.

İşaret	Anlamı
`@port-deviation:none`	Önemli bir sapma olmadan doğrudan 1:1 uyarlaması
`@port-deviation:async`	PHP, async/await yerine eşzamanlı kod kullanır
`@port-deviation:storage`	Farklı veri yapıları (PHP dizisi, JS Map/Set)
`@port-deviation:types`	TypeScript türleri yerine PHPDoc açıklamaları
`@port-deviation:sourcemaps`	Kaynak haritası takibi yoktur
`@port-deviation:enum`	PHP sabitleri, TypeScript enum'ları yerine kullanılır
`@port-deviation:errors`	Farklı hata işleme yaklaşımı
`@port-deviation:replacement`	Harici kitaplığın yerine geçen PHP uygulaması (e.g. lightningcss)
`@port-deviation:helper`	Özgün sürümde bulunmayan, PHP'e özgü yardımcı
`@port-deviation:performance`	Özdeş çıktıyı koruyan, PHP'e özgü optimizasyon
`@port-deviation:omitted`	Modülün/özelliğin tamamı uyarlanmamıştır (kapsam dışı)

@port-deviation:performance işaretleri ve eşdeğerliğin nasıl sağlandığı için bkz. Performans ve test.