إنشاء وحدة Magento 2 مخصصة من الصفر (دليل 2026)

Magento 2 هي واحدة من أكثر منصات التجارة الإلكترونية قابلية للتوسع. إن إنشاء وحدة مخصصة من الصفر هو مهارة أساسية تتيح تخصيصات الأعمال والتكامل مع الجهات الخارجية وتحسينات الأداء دون تعديل ملفات Magento الأساسية.

جدول المحتويات

1. المتطلبات الأساسية
2. هيكل الوحدة
3. إنشاء هيكل الدليل
4. registration.php
5. module.xml
6. تفعيل الوحدة
7. إضافة وحدة تحكم ومسار
8. إنشاء نموذج و ResourceModel
9. حقن التبعيات
10. المراقب / الحدث
11. أفضل ممارسات النشر
12. الأخطاء الشائعة
13. الأسئلة الشائعة

المتطلبات الأساسية

نصيحة SEO: إذا كنت تبني إضافة للتوزيع عبر Adobe Commerce Marketplace، فاتبع معايير البرمجة الرسمية من البداية.

هيكل الوحدة

الوحدة النمطية في Magento 2 تتبع بنية صارمة:

app/code/Vendor/ModuleName/
├── registration.php
├── etc/
├── Controller/
├── Model/
├── Block/
├── view/
└── Setup/

الخطوة 1 — إنشاء هيكل الدليل

mkdir -p app/code/MagentoMastery/HelloWorld/etc/frontend
mkdir -p app/code/MagentoMastery/HelloWorld/Controller/Index
mkdir -p app/code/MagentoMastery/HelloWorld/Model/ResourceModel/ExampleModel
mkdir -p app/code/MagentoMastery/HelloWorld/view/frontend/{layout,templates}
mkdir -p app/code/MagentoMastery/HelloWorld/Setup

الخطوة 2 — registration.php

use Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'MagentoMastery_HelloWorld',
    __DIR__
);

الخطوة 3 — module.xml

<module name="MagentoMastery_HelloWorld" setup_version="1.0.0">
</module>

الخطوة 4 — تفعيل الوحدة

php bin/magento module:enable MagentoMastery_HelloWorld
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

الخطوة 5 — إضافة وحدة تحكم ومسار

حدد المسار في routes.xml وأنشئ وحدة تحكم تطبق HttpGetActionInterface.

أفضل ممارسة لعام 2026: استخدم HttpGetActionInterface و HttpPostActionInterface بدلاً من تمديد الكلاس القديم Action.

الخطوة 6 — إنشاء نموذج و ResourceModel

يستخدم Magento نمط Model / ResourceModel / Collection:

• Model: منطق الأعمال
• ResourceModel: الوصول إلى قاعدة البيانات
• Collection: استرجاع البيانات وتصفيتها

الخطوة 7 — حقن التبعيات

مثال di.xml:

<preference for="Vendor\Module\Api\ExampleInterface"
            type="Vendor\Module\Model\ExampleModel"/>

الخطوة 8 — المراقب / الحدث

تسمح المراقبون بالتفاعل مع أحداث Magento دون تعديل الكلاسات الأساسية.

مثال لحدث:

<event name="catalog_product_save_after">
    <observer name="vendor_product_save"
              instance="Vendor\Module\Observer\ProductSaveAfter"/>
</event>

الخطوة 9 — أفضل ممارسات النشر

php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento setup:static-content:deploy -f
php bin/magento cache:flush

أفضل ممارسات التطوير

• استخدم declare(strict_types=1).
• فضّل حقن التبعيات عبر المنشئ.
• تجنب الاستخدام المباشر لـ ObjectManager.
• استخدم Schema/Data Patches بدلاً من InstallSchema كلما أمكن.
• اكتب اختبارات الوحدة والتكامل.
• اتبع معايير البرمجة PSR-12.

الأخطاء الشائعة

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

هل يجب استخدام InstallSchema أم DB Patches؟

DB Patches (DataPatchInterface و SchemaPatchInterface) هي الطريقة الموصى بها في إصدارات Magento الحديثة.

وحدتي ترجع 404. ماذا يجب أن أتحقق؟

1. تحقق من routes.xml
2. تحقق من تسمية وحدة التحكم وحالة الأحرف
3. امسح التخزين المؤقت
4. أعد ترجمة DI

الخلاصة

لديك الآن الأساس لوحدة Magento 2 جاهزة للإنتاج تشمل وحدات التحكم والنماذج وحقن التبعيات والمراقبين.

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

• تنفيذ Service Contracts
• بناء REST APIs مخصصة
• استكشاف محللات GraphQL
• إضافة اختبارات التكامل
• تخصيص صفحة الدفع في Magento 2 — إضافة حقول وتجاوز مكونات Knockout وبناء خطوات مخصصة

هل تحتاج إلى وحدة جاهزة للإنتاج وفق معايير Magento؟ اطلع على خدمات تطوير الوحدات المخصصة .