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

تجمع هذه الصفحة ما تحتاج إلى معرفته قبل الترقية أو الاعتماد على تطابق المخرجات: متطلبات بيئة التشغيل، وإصدار TailwindCSS الذي يتبعه النقل، والمواضع التي يختلف فيها TailwindPHP عن TailwindCSS عمدًا، وملاحظات كل إصدار. يوجد السجل الكامل في [CHANGELOG.md](https://github.com/inline0/tailwindphp/blob/main/CHANGELOG.md).

## المتطلبات

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

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

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

يتتبع الإصدار 1.7.0 **TailwindCSS v4.3.3**. ومستودع المنبع مثبت كوحدة فرعية من git في `reference/tailwindcss`، ومجموعات اختبارها مستخرجة من تلك النسخة المثبتة، والاختبارات البالغ عددها 4,427 تُشغّل عند كل دفع (راجع [الأداء والاختبارات](https://tailwindphp.inline0.dev/ar/docs/advanced/performance)). تتبع الإضافات المنقولة `@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()`](https://tailwindphp.inline0.dev/ar/docs/api#twextractcandidatesfromstrings) أو `@source inline("…")`. وتتجاهل API صيغ المسارات في `@source`، ولا يراعيها CLI إلا جزئيًا (انظر أدناه).

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

| المجال | السلوك الحالي | المشكلة |
|---|---|---|
| CLI `@source` | لا تُطبّق المسارات والأنماط العامة؛ ويُفحص دليل ملف الإدخال بدلًا منها، كما أن `@source not` لا يستبعد شيئًا. راجع [ما الذي يفحصه CLI](https://tailwindphp.inline0.dev/ar/docs/cli#what-the-cli-scans) | [#8](https://github.com/inline0/tailwindphp/issues/8) |
| CLI `--optimize` | يُجري التصغير مثل `--minify` | [#9](https://github.com/inline0/tailwindphp/issues/9) |
| الخيارات الطويلة لـ CLI | يتم تجاهل `--input file.css` (المفصول بمسافة)؛ استخدم `--input=file.css` أو `-i file.css` | [#13](https://github.com/inline0/tailwindphp/issues/13) |
| متغيرات الإضافات | تُترجم متغيرات `addVariant()`/`matchVariant()` ومعدّلات عناصر الطباعة (`prose-headings:` …) دون محدداتها | [#10](https://github.com/inline0/tailwindphp/issues/10) |
| وحدات الماكرو `@apply` | يُحذف `@apply --my-mixin;` بدل تمريره كما هو | [#12](https://github.com/inline0/tailwindphp/issues/12) |
| الاستيرادات المرجعية | تكون المخرجات فارغة عندما يسبق استيراد مرجعي استيراد الأدوات؛ ولا تأثير لـ `@import "tailwindcss" reference` | [#14](https://github.com/inline0/tailwindphp/issues/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`) بعد الترقية. وتبطل ذاكرة حالة [المترجم](https://tailwindphp.inline0.dev/ar/docs/advanced/caching#compiler-state-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 لكل صفحة من مترجم طويل العمر.