CONVIRO
Engineering

كيفية تثبيت إضافة Magento 2 باستخدام Composer: دليل خطوة بخطوة

شرح عملي لتثبيت إضافة Magento 2 باستخدام Composer: المستودعات الخاصة، وملف auth.json، وأمر setup:upgrade، وخطوات وضع الإنتاج، والتحديث، وإلغاء التثبيت، والأخطاء الشائعة.

كونفيرو
19 نوفمبر 20267 دقيقة قراءة
كيفية تثبيت إضافة Magento 2 باستخدام Composer: دليل خطوة بخطوة
متوفر في:PLFRESENDEETNLITARPTLTTR
في هذه المقالة

عند تثبيت إضافة Magento 2 باستخدام Composer، تضيف مستودع المورّد (مع بيانات الاعتماد إذا كان خاصًا)، وتشغّل composer require، وتفعّل الوحدة، وتشغّل bin/magento setup:upgrade، ثم تجمّع الشيفرة (compile) وتنشر المحتوى الثابت (static content) إذا كان المتجر في وضع الإنتاج، وأخيرًا تمسح ذاكرة التخزين المؤقت. هي بضعة أوامر فقط، لكن ترتيبها ووضع النشر (deploy mode) يصنعان الفرق.

يشرح هذا الدليل التسلسل كاملًا باستخدام إضافة Conviro for Magento المجانية مثالًا تطبيقيًا، ثم يتناول التحديث وإلغاء التثبيت والأخطاء التي يُرجَّح أن تواجهها.

أهم النقاط

  • شغّل كل أمر من المجلد الجذر لـMagento (ماجنتو) بصفتك مالك نظام الملفات، بعد أخذ نسخة احتياطية، وفي بيئة التجربة (staging) أولًا.
  • يحتاج وضع المطوّر (developer mode) إلى setup:upgrade ومسح ذاكرة التخزين المؤقت؛ أما وضع الإنتاج (production mode) فيحتاج أيضًا إلى تجميع الشيفرة ونشر المحتوى الثابت.
  • ألغِ التثبيت بالترتيب العكسي: نظّف التكامل أولًا، ثم عطّل الوحدة، واحذفها، وشغّل الترقية (upgrade).

قبل أن تبدأ: المتطلبات المسبقة

تحقق من هذه النقاط قبل المساس ببيئة الإنتاج:

  • وصول SSH وComposer على الخادم. فالتثبيت القائم على Composer لا يمكن إجراؤه من لوحة الإدارة.
  • نسخة احتياطية حديثة من الشيفرة وقاعدة البيانات، ويُفضَّل وجود نسخة تجريبية للاختبار عليها.
  • المستخدم الصحيح. شغّل الأوامر بصفتك مالك نظام الملفات، لا بصفة root، وإلا ستتسبب في مشكلات في الصلاحيات.
  • وضع النشر لديك. تحقق منه بالأمر bin/magento deploy:mode:show.
  • فترة صيانة لبيئة الإنتاج: bin/magento maintenance:enable قبل البدء، وbin/magento maintenance:disable بعد الانتهاء.

وبالنسبة إلى إضافة Conviro تحديدًا، تحتاج أيضًا إلى Magento Open Source 2.4.4 أو أحدث مع PHP 7.4 أو 8.1–8.4، وعنوان URL للمتجر يعمل بـHTTPS، ومهام cron في Magento قيد التشغيل، واتصال HTTPS صادر إلى api.conviro.io. وقد اختُبر تثبيت الإضافة (الإصدار 1.4.1 وقت كتابة هذا المقال) على:

Magento PHP القالب
2.4.4-p13 8.1 Luma
2.4.7-p4 8.3 Luma
2.4.9 8.4 Luma وHyvä 1.5.2

يعمل Adobe Commerce (أدوبي كوميرس) على إطار العمل نفسه لكنه لم يُختبر بعد، وHyvä Checkout غير مُختبر، أما المتاجر التي تعمل بالإصدارات 2.4.0–2.4.3 فتبقى على الإصدار 1.3.5 من الإضافة.

كيفية تثبيت إضافة Magento 2 باستخدام Composer خطوة بخطوة

الخطوة 1: أضف مستودع Composer وبيانات الاعتماد

تُوزَّع الإضافات الخاصة من مستودع Composer التابع للمورّد نفسه. من المجلد الجذر لـMagento:

composer config repositories.conviro composer https://repo.conviro.io
composer config http-basic.repo.conviro.io api <CONVIRO_API_KEY>

يضيف الأمر الأول المستودع إلى composer.json. ويحفظ الثاني بيانات الاعتماد في auth.json بجواره. وفي حالة Conviro، اسم المستخدم هو api، وكلمة المرور مفتاح API من Developers → API Keys في لوحة تحكم Conviro. ولمزيد من المعلومات عن واجهة API في Conviro، راجع صفحة المطوّرين.

أبقِ auth.json خارج نظام إدارة الإصدارات (version control). فمفاتيح repo.magento.com الخاصة بك تكون عادةً في الملف نفسه.

الخطوة 2: شغّل composer require وsetup:upgrade

composer require conviro/module-aichat
bin/magento module:enable Conviro_AiChat
bin/magento setup:upgrade

هذه الأوامر الثلاثة هي جوهر تثبيت أي وحدة (module) في Magento 2:

  1. composer require ينزّل الحزمة إلى vendor/ ويسجلها في composer.json وcomposer.lock. احفظ الملفين كليهما في المستودع (commit) حتى تثبّت كل البيئات الإصدار نفسه.
  2. module:enable يسجّل الوحدة في app/etc/config.php.
  3. setup:upgrade يطبّق مخطط قاعدة البيانات وتصحيحات البيانات (data patches) الخاصة بالوحدة، ويحدّث سجل الوحدات.

الخطوة 3: جمّع الشيفرة، وانشر المحتوى، وامسح ذاكرة التخزين المؤقت

في وضع الإنتاج، لا تُبنى الشيفرة المولَّدة والملفات الثابتة عند الطلب، لذا شغّل:

bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f

في وضع المطوّر، تخطَّ الأمرين. وفي كلا الوضعين، اختم بالأمر التالي:

bin/magento cache:flush

ثم تحقق من أن الوحدة مفعّلة، واخرج من وضع الصيانة:

bin/magento module:status Conviro_AiChat
bin/magento maintenance:disable

الخطوة 4: اربط الإضافة من لوحة الإدارة

تحتاج معظم الإضافات إلى ضبط بعد التثبيت. وفي حالة Conviro، افتح Stores › Settings › Conviro Setup. يبدأ معالج من 7 خطوات بفحص البيئة، ثم تنقر على Connect to Conviro، وتوافق على المتجر في لوحة تحكم Conviro، وتعود إلى Magento. ولا يُنسخ أي مفتاح API أو رمز وصول (token) إلى Magento.

ينشئ المعالج تكاملًا في Magento بأقل قدر من الصلاحيات (OAuth 1.0a)، ويتيح لك اختيار واجهات المتجر (store views) وما تجري مزامنته وإجراءات الذكاء الاصطناعي المسموح بها، ثم يتحقق من كل شيء بحدث تجريبي. وبعد ذلك، تفحص بطاقة Integration Health (سلامة التكامل) ضمن Stores › Configuration › Conviro › AI Chat الاتصال، والمصادقة، والـWebhooks، والكتالوج، والطلبات، ومهام cron، والإصدار، والبيئة، مع تعليمات للإصلاح. وتشرح صفحة التثبيت وتوثيق التثبيت كل خطوة. ويتطلب الربط باقة Conviro تتضمن الوصول إلى API، أي باقة Pro أو أعلى (راجع الأسعار).

تحديث وحدة Magento 2 وإلغاء تثبيتها

التحديث

composer update conviro/module-aichat
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

كما في السابق، لا تجمّع الشيفرة ولا تنشر المحتوى إلا في وضع الإنتاج. وتعرض لوحة إدارة Magento إشعارًا بالأمر الدقيق عند صدور إصدار جديد، وتبقى إعداداتك ومفتاح API والتكامل كما هي.

إلغاء التثبيت

الترتيب مهم: فإلغاء الربط يتم من معالج الإعداد، وهذا المعالج يختفي بمجرد حذف الوحدة.

  1. ألغِ الربط من معالج إعداد Conviro.
  2. عطّل الوحدة: bin/magento module:disable Conviro_AiChat
  3. احذف الحزمة: composer remove conviro/module-aichat
  4. شغّل bin/magento setup:upgrade.

في وضع الإنتاج، أعِد تجميع الشيفرة، وأعِد نشر المحتوى الثابت، وامسح ذاكرة التخزين المؤقت كالمعتاد. وتحذف Conviro بيانات المتجر بعد 30 يومًا من إلغاء الربط، أو فورًا إذا اخترت ذلك. ويسرد توثيق إلغاء التثبيت كل الخطوات.

الأخطاء الشائعة وكيفية إصلاحها

العَرَض السبب المرجّح الحل
رسالة "Allowed memory size exhausted" أثناء تشغيل Composer حد الذاكرة في PHP شغّل COMPOSER_MEMORY_LIMIT=-1 composer require ...
نفاد الذاكرة أثناء تجميع الشيفرة حد الذاكرة في سطر الأوامر (CLI) شغّل php -d memory_limit=2G bin/magento setup:di:compile
خطأ 401 أو طلب بيانات الاعتماد من المستودع مفتاح أو اسم مستخدم خاطئ أعِد تشغيل أمر http-basic؛ واسم المستخدم هو api
رسالة "Permission denied" في generated/ أو var/ أو pub/static/ تشغيل الأوامر بصفة root أو بمستخدم خاطئ صحّح ملكية الملفات، ثم أعِد التشغيل بصفتك مالك نظام الملفات
رسالة "Please upgrade your database" لم يُشغَّل setup:upgrade شغّل bin/magento setup:upgrade
توقّف مزامنة البيانات، وتنبيه بطاقة السلامة إلى cron مهام cron لا تعمل شغّل bin/magento cron:install وتحقق من crontab -l

مهام cron أهم مما تبدو. إذ تكتب Conviro أحداث الدفع والتسجيل وحفظ المنتجات في قائمة انتظار محلية تتولى مهام cron في Magento إرسالها في الخلفية. كما صُممت الإضافة بحيث لا تستدعي صفحات الواجهة الأمامية للمتجر Conviro عبر PHP، وتستمر معالجة الطلبات حتى إذا تعذّر الوصول إلى Conviro. اختبر المسار كاملًا في بيئة التجربة أولًا؛ وتفيدك قائمة اختبار الشات بوت بالذكاء الاصطناعي بعد التثبيت.

الأسئلة الشائعة

هل أحتاج إلى تشغيل setup:di:compile في وضع المطوّر؟

لا. يولّد وضع المطوّر الشيفرة عند الطلب، لذا يكفي setup:upgrade وcache:flush بعد تثبيت وحدة. أما في وضع الإنتاج، فشغّل setup:di:compile وsetup:static-content:deploy أيضًا، وإلا فقد تتعطل الواجهة الأمامية للمتجر ولوحة الإدارة بسبب غياب الشيفرة المولَّدة والملفات الثابتة.

أين يحفظ Composer بيانات الاعتماد الخاصة بمستودع خاص؟

يكتبها الأمر composer config http-basic.<host> <user> <password> في auth.json في المجلد الجذر لمشروعك، بجوار composer.json. وأضف --global لحفظها بدلًا من ذلك في مجلد Composer الرئيسي الخاص بمستخدمك. وفي الحالتين، أبقِ auth.json خارج نظام إدارة الإصدارات حتى لا تتسرب المفاتيح.

كيف أتحقق من أن وحدة Magento 2 مفعّلة؟

شغّل bin/magento module:status لعرض الوحدات المفعّلة والمعطّلة، أو أضف اسم الوحدة، مثل bin/magento module:status Conviro_AiChat. وإذا ظهرت معطّلة، فشغّل module:enable، ثم setup:upgrade وامسح ذاكرة التخزين المؤقت.

هل يمكنني تثبيت إضافة Magento دون وصول SSH؟

ليس باستخدام Composer. تحتاج إضافة Conviro إلى وصول SSH أو CLI وإلى Composer على الخادم. وإذا كانت استضافتك لا توفرهما، فاطلب من مزوّد الاستضافة أو الوكالة التي تتعامل معها تنفيذ التثبيت. وفي باقة Enterprise، يثبّت فريق Conviro الإضافة دون تكلفة إضافية.

الخطوات التالية

نفّذ التثبيت في بيئة التجربة، وأكمل خطوات معالج الإعداد، وراجع بطاقة Integration Health قبل تكرار العملية في بيئة الإنتاج. ولجولة كاملة على ما تفعله الإضافة بعد ربطها، اقرأ دليلنا عن إضافة المحادثة بالذكاء الاصطناعي لـMagento 2. هل أنت مستعد للربط؟ أنشئ حسابك في Conviro.

شارك:

نشرت من قبل

كونفيرو

مشاركة الرؤى حول دعم العملاء المدعوم بالذكاء الاصطناعي وأتمتة روبوتات الدردشة واستراتيجيات نمو SaaS.

البناء على كونفيرو

قم بتوصيل مسارات عمل المحادثة بالمكدس الخاص بك

قم بمراجعة موارد المطور وأنماط التكامل قبل تصميم التنفيذ.

مقالات ذات صلة

المزيد من المشاركات