التوافق والترقية

تجمع هذه الصفحة ما تحتاج إلى معرفته قبل الترقية أو الاعتماد على تطابق المخرجات: متطلبات بيئة التشغيل، وإصدار TailwindCSS الذي يتبعه النقل، والمواضع التي يختلف فيها TailwindPHP عن TailwindCSS عمدًا، وملاحظات كل إصدار. يوجد السجل الكامل في CHANGELOG.md.

المتطلبات

• PHP 8.2 أو أحدث. تعمل مجموعة الاختبارات على PHP 8.2 و8.3 و8.4.
• إضافتا ctype وmbstring. يستدعي المترجم ctype_* وmb_chr(). تأتي كلتاهما مع معظم إصدارات PHP ومع صور Docker الرسمية، لكن composer.json لا يعلنهما بعد (#11)، لذا فإن البناء بدونهما يثبّت الحزمة ثم يفشل وقت التشغيل.
• اختياري: pcntl يتيح لوضع CLI ذي --watch التوقف بسلاسة عند SIGINT/SIGTERM. ويظل وضع المراقبة يعمل من دونه.

لا يتضمن ذلك Node.js أو FFI أو ملفات تنفيذية أصلية.

إصدار TailwindCSS المتتبَّع

يتتبع الإصدار 1.7.0 TailwindCSS v4.3.3. ومستودع المنبع مثبت كوحدة فرعية من git في reference/tailwindcss، ومجموعات اختبارها مستخرجة من تلك النسخة المثبتة، والاختبارات البالغ عددها 4,427 تُشغّل عند كل دفع (راجع الأداء والاختبارات). تتبع الإضافات المنقولة @tailwindcss/typography و@tailwindcss/forms، وتتبع أدوات الأصناف clsx وtailwind-merge وCVA، وكل منها مثبت بالطريقة نفسها.

الفروق المعروفة عن TailwindCSS

تفاصيل التسلسل

تطابق CSS المُنشأة مجموعات الاختبار المرجعية. وتختلف بعض تفاصيل التسلسل عما يطبعه CLI الخاص بـ TailwindCSS، دون أن يغيّر أي منها التتابع:

• بادئات الموردين: عندما يصدر المرجع سطر -webkit-* المكتوب وسطرًا مُنشأً، يصدر TailwindPHP سطرًا واحدًا.
• تبقى العناصر الزائفة المخفّضة المستوى (::file-selector-button، ::-webkit-datetime-edit-*) ضمن قوائم المحددات المكتوبة بدلًا من فصلها إلى قاعدة لكل عنصر زائف.
• تبقى السلاسل المكتوبة بعلامة اقتباس مفردة على حالها ('Segoe UI') بدل تطبيعها إلى علامات اقتباس مزدوجة.
• لا تُجمع الخصائص الطويلة المتزامنة في صيغة مختصرة (فمخرجات Tailwind نفسها لا تحتاج إلى ذلك).
• يُبقي .p-0 على padding: 0px حيث يصدر المرجع CLI padding: 0، لأن مجموعة الاختبارات المستخرجة تثبّت صيغة 0px. ويختصرها المصغّر إلى 0.

غير المشمول

TailwindPHP مترجم CSS. وهو لا يتضمن أدوات التحرير في منظومة Tailwind (IntelliSense والإكمال التلقائي وترتيب الأصناف) ولا خرائط المصدر، لذا لا يتضمن CLI خيار --map.

فحص المحتوى

يقرأ tw::generate() وTailwindCompiler::generate() أسماء الأصناف من سِمتي class وclassName فقط. لأسماء الأصناف الموجودة في سلاسل PHP أو JavaScript، استخدم tw::extractCandidatesFromStrings() أو @source inline("…"). وتتجاهل API صيغ المسارات في @source، ولا يراعيها CLI إلا جزئيًا (انظر أدناه).

المشكلات المعروفة في الإصدار الحالي

المجال	السلوك الحالي	المشكلة
CLI @source	لا تُطبّق المسارات والأنماط العامة؛ ويُفحص دليل ملف الإدخال بدلًا منها، كما أن @source not لا يستبعد شيئًا. راجع ما الذي يفحصه CLI	#8
CLI --optimize	يُجري التصغير مثل --minify	#9
الخيارات الطويلة لـ CLI	يتم تجاهل --input file.css (المفصول بمسافة)؛ استخدم --input=file.css أو -i file.css	#13
متغيرات الإضافات	تُترجم متغيرات addVariant()/matchVariant() ومعدّلات عناصر الطباعة (prose-headings: …) دون محدداتها	#10
وحدات الماكرو @apply	يُحذف @apply --my-mixin; بدل تمريره كما هو	#12
الاستيرادات المرجعية	تكون المخرجات فارغة عندما يسبق استيراد مرجعي استيراد الأدوات؛ ولا تأثير لـ @import "tailwindcss" reference	#14

ملاحظات الترقية

1.7.0

• تتغير المخرجات على مستوى البايتات مقارنةً بـ 1.6.x، مع بقائها مكافئة وظيفيًا للمرجع v4.3.3 الخاص بـ TailwindCSS. ومن التغييرات الملحوظة:
  • مضاعفات التباعد: يصدر p-1 القيمة padding: var(--spacing) بدلًا من calc()، ويصدر المضاعف 0 طولًا يساوي صفرًا مجردًا.
  • تتحول الكسور إلى نسب مئوية: يصدر w-1/2 القيمة width: 50%.
  • الألوان: يُسلسل السطوع في oklch()/oklab() كنسبة مئوية (oklch(62.3% .214 259.815))، ويُختصر white وblack إلى #fff و#000.
  • تُسلسل العناصر الزائفة في CSS2 بنقطتين مفردتين (:before، :after، :first-letter، :first-line).
  • تُسطّح قواعد @media/@supports/@container المتداخلة في مواضعها وبترتيب المصدر بدل نقلها إلى النهاية؛ وتُعاد التصريحات إلى ترتيب lightningcss، وتُحذف التصريحات المكررة التي جرى حجبها.
• تُبطل ذاكرات التخزين المؤقت المفهرسة بالمخرجات مرة واحدة. لا يتضمن مفتاح ذاكرة الملفات في tw::generate() إصدار TailwindPHP؛ لذا شغّل tw::clearCache() (أو الدليل الذي مررته بوصفه cache) بعد الترقية. وتبطل ذاكرة حالة المترجم نفسها.
• جديد: @variant في CSS المؤلف، ووحدات ماكرو CSS في @apply، و@media reference و@import "…" reference، ومحرك --value()/--modifier() الكامل لـ @utility الوظيفية، والتحقق الأكثر صرامة من أسماء @utility، وخيار tw::compile() الخاص بـ polyfills.

1.6.1

• جديد: أداة container (width: 100% بالإضافة إلى max-width واحد لكل نقطة توقف).
• تُسجّل الآن متغيرات --tw-* المركّبة (translate وscale وrotate وskew والمرشحات وغيرها) في @property، لتكتسب أوراق الأنماط قواعد @property تلك، وتعمل التحويلات مثل translate-x-7 في المتصفح.

1.6.0

• جديد: ذاكرة حالة المترجم الدائمة (stateCacheFile في tw::compile() وTailwindCompiler، StateCache\compileCssCached())، ودوال parseCssState()/finalizeCssState()/compileParsed() المنفصلة. تعمل الاستدعاءات الحالية كما كانت تمامًا.

1.5.0

• يجب أن تضيف الفئات الفرعية لـ TailwindCompiler التي تتجاوز generate() أو css() المعامل الاختياري bool $minify = false؛ إذ يرفض PHP التجاوزات التي تحذف معاملًا اختياريًا من الفئة الأصل.
• تأتي المخرجات المصغّرة من المُسلسِل، لذا تختلف بايتاتها قليلًا عن 1.4.x (وتُبطل ذاكرات التخزين المؤقت المفهرسة بالمخرجات المصغّرة مرة واحدة).
• جديد: generateExact() وcssExact() لتوليد CSS لكل صفحة من مترجم طويل العمر.