دليل كامل: bin/magento setup:upgrade مقابل setup:di:compile

إذا سبق لك أن حدقت في شاشة الطرفية قبل نشر Magento 2 تتساءل “هل أشغل كليهما؟ بأي ترتيب؟ هل أحتاج حقًا إلى إعادة الترجمة؟” — فأنت لست وحدك.

هذان الأمران هما حارسا بوابة كل نشر Magento. ومع ذلك، يعاملهم معظم المطورين مثل التعاويذ السحرية: نسخ، لصق، دعاء. في هذا الدليل، سأفكك البنية خلف كلا الأمرين حتى تعرف بالضبط ما يحدث تحت الغطاء، متى يكون كل أمر إلزاميًا، ولماذا الترتيب مهم.

لا تخمين. لا DevOps بالتقليد. فقط وضوح.

الفرق الجوهري في جملة واحدة

setup:upgrade يدير قاعدة البيانات ودورة حياة الوحدات.
setup:di:compile يولد كود PHP لكي يعمل التطبيق فعليًا.

يحلان مشكلتين مختلفتين تمامًا. الخلط بينهما يشبه الخلط بين المهندس المعماري وفريق البناء — كلاهما أساسي، لكنهما لا يؤديان نفس المهمة.

ماذا يفعل bin/magento setup:upgrade فعليًا

عند تشغيل هذا الأمر، يقوم Magento بـ فحص دورة حياة على مستوى النظام عبر أربع طبقات متميزة:

1. تسجيل الوحدات وتحديثات المخطط

يقوم Magento بمسح app/etc/config.php ومقارنته بنظام الملفات. إذا أضفت وحدة جديدة (أو حدثت وحدة موجودة)، فإنه:

• يسجل الوحدة في قاعدة البيانات (جدول setup_module)
• ينفذ أي نصوص InstallSchema أو UpgradeSchema
• يطبق تصحيحات البيانات (تغييرات db_schema_whitelist.json)

اعتبرها: تحديث المخططات الهيكلية وأساسات المبنى.

2. ترجمة حقن التبعيات (جزئية)

هنا يصبح الأمر مثيرًا للاهتمام. setup:upgrade يطلق بالفعل عملية ترجمة خفيفة — لكن فقط للوحدات الجديدة أو المعدلة. يولد الكود الأدنى اللازم لجعل الوحدة الجديدة قابلة للتشغيل.

المشكلة: هذه ليست setup:di:compile كاملة. لن تحسن قاعدة الكود بأكملها. لن تكتشف تبعيات بين الوحدات تغيرت في وحدات لم تلمسها.

3. مسح ذاكرة التخزين المؤقت

يمسح Magento ذاكرات تخزين مؤقت محددة تتعلق بالتكوين والتخطيط. هذا يضمن أن المتجر يعكس تغييرات المخطط الخاصة بك فورًا.

4. تشغيل تصحيحات البيانات

أي تصحيحات بيانات جديدة (مُرقمة أو غير مُرقمة) تنفذ هنا. هذا هو المكان الذي تعمل فيه بيانات العينة أو التكوينات الافتراضية أو نصوص الترحيل.

متى يكون setup:upgrade إلزاميًا؟

ماذا يفعل bin/magento setup:di:compile فعليًا

هذا الأمر هو مولد الكود في Magento. يقرأ قاعدة الكود بأكملها — كل di.xml، كل مُنشئ، كل تفضيل، كل إضافة — ويولد كلاسات PHP محسّنة تعيش في generated/.

المراحل الأربع للتوليد

1. الاعتراض (الإضافات)     → generated/code/Magento/.../Plugin
2. التفضيلات والأنواع الافتراضية → generated/code/.../Preference
3. الوكلاء والمصانع         → generated/code/.../Proxy, Factory
4. المعترضات (around/before/after) → generated/code/.../Interceptor

1. معترضات للإضافات

كل كلاس لديه إضافة يحصل على كلاس Interceptor مولّد. هذا الغلاف يفوض إلى دوال before و around و after. بدون ترجمة، كان سيضطر Magento لفعل ذلك عبر انعكاس بطيء في وقت التشغيل.

2. وكلاء للتبعيات الثقيلة

إذا كانت وسيطة المُنشئ محددة النوع لكنها مُعلَمة ككسولة (أو إذا اكتشف Magento خطر تبعية دائرية)، فإنه يولد كلاس Proxy. هذا يؤخر الإنشاء حتى يتم استخدام الكائن فعليًا.

3. مصانع للكلاسات غير القابلة للحقن

الكلاسات التي لا يمكن ربطها تلقائيًا (مثل تلك التي تتطلب معاملات وقت التشغيل) تحصل على كلاسات Factory مولّدة في generated/code/.

4. التفضيلات والأنواع الافتراضية

عندما تعلن عن <preference for="..." type="..."/> أو <virtualType .../>، يولد Magento منطق التوجيه ليحل الحاوية محل التنفيذ الصحيح فورًا.

المخرجات الحرجة: دليل generated/

بعد تشغيل setup:di:compile، يحتوي دليل generated/ على آلاف ملفات PHP. في وضع الإنتاج، يقرأ Magento من هنا فقط. لا يلمس أبدًا ملفاتك الأصلية في app/code/ أو vendor/ لحل الكلاسات.

لهذا السبب الأمر غير قابل للتفاوض في الإنتاج.

متى يكون setup:di:compile إلزاميًا؟

تسلسل النشر الذي يعمل فعليًا

الآن بعد أن فهمت البنية، يصبح ترتيب النشر الصحيح واضحًا:

# الخطوة 1: وضع المتجر في وضع الصيانة
bin/magento maintenance:enable

# الخطوة 2: تطبيق تغييرات الكود (git pull، rsync، إلخ)
# ... script النشر الخاص بك ...

# الخطوة 3: تثبيت/تحديث الوحدات والمخطط
bin/magento setup:upgrade

# الخطوة 4: توليد كود محسّن لكل قاعدة الكود
bin/magento setup:di:compile

# الخطوة 5: نشر الأصول الثابتة (إذا تغيرت السمات)
bin/magento setup:static-content:deploy -f

# الخطوة 6: مسح ذاكرات التخزين المؤقت
bin/magento cache:flush

# الخطوة 7: تعطيل وضع الصيانة
bin/magento maintenance:disable

لماذا هذا الترتيب مهم

1. setup:upgrade قبل setup:di:compile: الوحدات الجديدة يجب تسجيلها في قاعدة البيانات قبل ترجمة ملفات di.xml الخاصة بها. إذا ترجمت أولاً، لا يعرف Magento أن الوحدة الجديدة موجودة.

2. setup:di:compile قبل cache:flush: الترجمة تولد ملفات في generated/. مسح ذاكرات التخزين المؤقت قبل الترجمة لا طائل منه — ستكون تمسح ذاكرات تخزين مؤقت لكود قديم.

3. setup:static-content:deploy بعد الترجمة: النشر الثابت يعتمد أحيانًا على كلاسات مولّدة (لترجمة LESS، دمج requirejs-config، إلخ).

وضع الإنتاج مقابل وضع المطور: فخ الترجمة

هذا هو المكان الذي يخسر فيه معظم المستقلين ساعات في تصحيح أخطاء “يعمل على جهازي”.

الفخ: في وضع المطور، يمكنك تخطي setup:di:compile تمامًا. Magento سيولّد المعترضات والوكلاء بشكل كسول عند طلبها. هذا أسرع للتطوير المحلي.

الكارثة: تنشر إلى الإنتاج بدون ترجمة. أول طلب عميل يشغل كلاسًا غير موجود في generated/. Magento يرمي خطأ فادحًا. متجرك معطل.

قاعدة أساسية: لا تنشر أبدًا إلى الإنتاج دون تشغيل setup:di:compile، حتى لو لم تغير أي ملفات di.xml. الترجمة عديمة التأثير — تشغيلها دون حاجة يكلف وقتًا، لكن تخطيها يكلف إيرادات.

السيناريوهات الشائعة: مصفوفة القرار

السيناريو أ: “أصلحت فقط خطأ في كلاس PHP”

• غيرت جسم دالة في app/code/Vendor/Module/Model/Something.php؟
• لا تغييرات في المُنشئ؟ لا تبعيات جديدة؟
• الإجراء: فقط امسح ذاكرة التخزين المؤقت. أي من الأمرين ليس ضروريًا تمامًا.
• نشر آمن: شغلهما على أي حال. يأخذ دقيقتين إضافيتين، يزيل الشك.

السيناريو ب: “قمت بتثبيت وحدة طرف ثالث جديدة”

• الإجراء: setup:upgrade ثم setup:di:compile.
• لماذا: الوحدة تحتاج تسجيل قاعدة بيانات وترجمة ملف di.xml الخاص بها.

السيناريو ج: “أضفت إضافة لتعديل سلوك الدفع”

• الإجراء: setup:di:compile إلزامي. setup:upgrade فقط إذا كانت وحدة جديدة.
• لماذا: الإضافات تُترجم إلى معترضات. بدون ترجمة، إضافتك غير مرئية لـ Magento.
• ذو صلة: اطلع على دليل تخصيص الدفع لأمثلة واقعية للإضافات في تدفق الدفع.

السيناريو د: “حدثت نواة Magento عبر Composer”

• الإجراء: دائمًا كلا الأمرين، بالترتيب.
• لماذا: تحديثات النواة تغير di.xml ومخططات قاعدة البيانات وغالبًا تضيف وحدات جديدة. لا تفترض أبدًا أن إصدارًا تصحيحيًا “آمن” للنشر دون أوامر دورة الحياة الكاملة.

السيناريو هـ: “عميلي يصرخ لأن الموقع وقع بعد النشر”

• الفحص 1: هل شغلت setup:upgrade؟ تحقق من جدول setup_module لعدم تطابق الإصدارات.
• الفحص 2: هل شغلت setup:di:compile؟ تحقق من generated/ لملفات المعترض المفقودة.
• الفحص 3: هل المتجر في وضع الإنتاج؟ شغل bin/magento deploy:mode:show.
• الخيار النووي: rm -rf generated/* var/cache/* var/page_cache/* وأعد تشغيل التسلسل الكامل.

تأثيرات الأداء التي يجب على كل رائد أعمال معرفتها

كمستقل أو صاحب وكالة، أنت لا تكتب الكود فقط — أنت تدير توقعات العملاء وتكاليف الخادم.

مدة setup:di:compile

نصيحة احترافية لمكالمات العملاء: لا تقل أبدًا “أنا أترجم” — قل “أنا أولد كود التطبيق المحسّن لضمان أوقات استجابة أقل من ثانية.” نفس الإجراء، قيمة مدركة مختلفة تمامًا.

متطلبات RAM

الترجمة مكثفة في استخدام الذاكرة. إذا كان خادم النشر لديك أقل من 2GB RAM، فإن الترجمة ستفشل أو تستخدم المبادلة (مما يجعلها أبطأ 10 مرات). خصص بنية تحتية كافية — إنها أرخص من التوقف عن العمل.

الترجمة المتوازية

يدعم Magento 2.4.6+ الترجمة المتوازية عبر:

bin/magento setup:di:compile --multi-threads=4

هذا يمكن أن يقلل وقت الترجمة بنسبة 40-60% على الخوادم متعددة النوى. أضف هذا إلى scripts النشر الخاصة بك فورًا.

حزمة أدوات التواصل للمستقل

عندما يسأل عميلك “لماذا يستغرق النشر 10 دقائق؟"، إليك النص الخاص بك:

“Magento يولّد آلاف ملفات PHP المحسّنة أثناء النشر — اعتبرها كبناء كل باب ونافذة مسبقًا قبل أن يدخل العملاء المتجر. تخطي هذا سيجعل الموقع أبطأ 10 مرات أو ينهار تمامًا. الـ 10 دقائق الآن توفر ساعات من التوقف لاحقًا.”

وعندما يسألون “هل يمكننا تخطي خطوة الترجمة للنشر بشكل أسرع؟”:

“يمكننا، لكن فقط إذا كنت موافقًا على أن الموقع قد يتعطل ويحمل في 8+ ثوانٍ بدلاً من أقل من ثانية. الترجمة هي ما يجعل Magento سريعًا في الإنتاج.”

أطر الضروريات التقنية كـ حماية للأعمال، وليس كمضايقات تقنية.

مرجع سريع: ورقة الغش

احفظ هذا. اطبعه. الصقه على شاشتك.

التسلسل الإلزامي: setup:upgrade → setup:di:compile → setup:static-content:deploy → cache:flush

الخلاصة: توقف عن التخمين، ابدأ بالهندسة المعمارية

الفرق بين مطور مبتدئ ومستشار كبير ليس معرفة أي الأوامر تشغيل — بل فهم لماذا توجد في بنية Magento.

setup:upgrade هو مدير المخطط ودورة حياة الوحدات.
setup:di:compile هو مولد الكود ومحسن الأداء.

شغلهما بالترتيب الخاطئ، تخطهما في الإنتاج، أو اخلط بين أغراضهما، وأنت لا تكسر نشرًا فقط — أنت تكسر شركة.

أتقن هذين الأمرين، وستكون أتقنت أساس كل نشر Magento. كل شيء آخر هو مجرد تفاصيل.

هل تخطط لترقية Magento أو تحتاج مساعدة في سير عمل النشر؟ اطلع على خدمات الترحيل والترقية .

وجدت هذا الدليل مفيدًا؟ أنشر تحليلات متعمقة مثل هذه كل أسبوع لرواد الأعمال والمطورين الناطقين بالعربية الذين يبنون مشاريع e-commerce جادة. تابعني للمزيد من محتوى بنية Magento بدون زخرفة.

Tags: #Magento2 #Ecommerce #Deployment #Backend #CLI #DevOps #FreelanceTips