المرحلة 01 · الأساسياتدرس 4 من 217 دقيقة قراءةآخر تحديث: 14 سبتمبر 2026

Lesson 04 / 21

Moduleهيكل الموديول.

Q: إيه أقل ملفات محتاجها عشان أعمل module في Magento 2؟

ملفين بس: registration.php اللي بيسجّل الموديول بـ ComponentRegistrar::register() باسمه الرسمي زي Vendor_Module، وetc/module.xml اللي بيعرّف اسمه والـ sequence بتاعه. بتحطهم في app/code/Vendor/Module/، وأي مجلّد تاني بتضيفه لما تحتاجه.

Q: ما الفرق بين app/code و vendor في Magento 2؟

app/code/ مكان الموديولات بتاعتك (custom)، وvendor/ فيه الموديولات اللي اتثبّتت عن طريق Composer زي Magento core والحزم الخارجية. متعدّلش حاجة في vendor/ أبدًا، ولو عايز تغيّر سلوك موديول core استخدم plugins أو events من موديولك.

Q: إزاي أفعّل module جديد في Magento 2؟

الترتيب المعتاد: bin/magento module:enable Vendor_Module وبعده bin/magento setup:upgrade وبعده bin/magento cache:clean. لو ضفت إعدادات DI أو شغّال production شغّل setup:di:compile، واتأكد إن الموديول اتفعّل بـ bin/magento module:status Vendor_Module.

Q: يعني إيه Area في Magento 2؟

الـ Area سياق تشغيل ليه إعداداته وملفاته: frontend لواجهة المتجر، وadminhtml للوحة التحكم، وwebapi_rest وwebapi_soap للـ APIs، وcrontab للمهام المجدولة، وglobal للمشترك. عشان كده etc/di.xml بيتطبّق على الكل، وetc/frontend/di.xml على الواجهة بس.

Q: إيه أهم ملفات مجلد etc في Magento 2 module؟

أهمهم module.xml (إجباري) وdi.xml للـ preferences والـ plugins والـ virtual types، وevents.xml لربط الـ observers، وdb_schema.xml لتعريف الجداول بالـ declarative schema. وفيه كمان acl.xml للصلاحيات، وcrontab.xml للـ cron jobs، وwebapi.xml لتعريف الـ REST endpoints.

Q: ليه الموديول بتاعي مش ظاهر في Magento 2؟

غالبًا نسيت تشغّل setup:upgrade أو cache:clean بعد ما فعّلته. ومن الأسباب كمان اختلاف اسم الموديول بين registration.php وmodule.xml، أو إن الـ namespace مش مطابق لمسار الملف.

Q: ما الفرق بين مجلد Block و templates في Magento 2؟

مجلّد Block/ في جذر الموديول فيه كلاسات PHP بتجهّز البيانات للعرض. أما view/frontend/templates/ فيه ملفات .phtml (HTML + PHP) اللي بتعرضها فعليًا، وملفات الـ layout/ XML بتحدد أنهي blocks تظهر فين في الصفحة.

أول احتكاك حقيقي بـ Magento. كل feature بتعملها بتعيش جوّه module. هنفهم كل مجلّد وملف ودوره ومتى تستخدمه — عشان لما تحتار "الملف ده يروح فين"، ترجعله وتعرف.

● أول موديول كل ملف ودوره متى تستخدمه

الـ module في Magento 2 وحدة مستقلة بتضيف feature، وأقل حاجة محتاجها ملفين: registration.php اللي بيسجّل اسم الموديول، و etc/module.xml اللي بيعرّفه. باقي المجلدات بتضيفها حسب الحاجة: etc للإعدادات، و Model و Controller و Block للكود، و view للواجهة. وبتفعّله بأمر module:enable وبعدين setup:upgrade.

// إزاي تستخدمه ده مرجع مش قصة. مش مطلوب تحفظه — مطلوب تفهم الفكرة العامة (كل حاجة معزولة في module، وكل نوع ملف ليه مكان)، وترجعله وقت الحاجة. المجلّدات اللي بالنجمة (★) هي الأهم في البداية.

يعني إيه Module؟

الوحدة الأساسية اللي Magento كله مبني منها.

إيه هو

الـ Module هو وحدة مستقلة بتضيف وظيفة معيّنة لـ Magento. كل حاجة في Magento — الكتالوج، الـ checkout، العملاء — كلها modules. حتى الكود بتاعك بيكون module.

ليه النظام ده

عشان العزل والمرونة. كل module منفصل، تقدر تفعّله أو تعطّله، تضيف أو تشيل، من غير ما تكسر الباقي. ده تطبيق مباشر لمبدأ الـ modularity.

تشبيه الـ modules زي قطع الليجو. كل قطعة مستقلة وليها شكل محدد، بس بتتركّب مع بعضها لتكوّن حاجة أكبر. تقدر تشيل قطعة وتحط غيرها من غير ما تهدّ المبنى كله.

فين بيتحط الكود

الـ modules بتاعتك بتكون في app/code/Vendor/Module/. الـ Vendor اسم شركتك/اسمك، والـ Module اسم الموديول.

الـ modules الأساسية بتاعة Magento بتكون في vendor/magento/. متعدّلهاش أبدًا — لو عايز تغيّر سلوكها، استخدم plugins/events من موديولك الخاص (Open/Closed).

• • •

الملفان الإجباريان

أقل موديول ممكن = ملفين بس. دول اللي بيخلّوه "موجود".

دوره

بيسجّل الموديول في نظام Magento. بيقول "أنا موجود، اسمي كذا، ومكاني كذا". من غيره، Magento مش هيعرف الموديول أصلًا.

registration.phpphp

use Magento\Framework\Component\ComponentRegistrar;

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

لاحظ اسم الموديول Vendor_Module بـ underscore — ده اسمه الرسمي في Magento (مختلف عن الـ namespace اللي بيستخدم backslash).

دوره

بيعرّف بيانات الموديول: اسمه، وأهم حاجة — الاعتماديات (dependencies) والترتيب. بيقول "أنا محتاج الموديولات دي تتحمّل قبلي".

etc/module.xmlxml

<config>
  <module name="Vendor_Module">
    <sequence>
      <!-- load these before me -->
      <module name="Magento_Catalog"/>
    </sequence>
  </module>
</config>

الـ sequence

مهم لما موديولك بيعتمد على تاني. مثلًا لو بتعمل plugin على method من الكتالوج، لازم الكتالوج يتحمّل الأول. الـ sequence بيضمن ده.

الملفين دول بس (registration + module.xml) كفاية عشان الموديول "يتسجّل ويشتغل". أي حاجة تانية بتضيفها حسب احتياجك.

• • •

الهيكل الكامل

الخريطة الكاملة للمجلّدات. النجمة (★) = الأكثر استخدامًا.

Vendor/Module/tree

registration.php       # ★ التسجيل
etc/                   # ★ الإعدادات (XML)
├─ module.xml          # ★ تعريف الموديول
├─ di.xml              # ★ الـ DI
├─ events.xml          # الـ observers
├─ db_schema.xml       # ★ الجداول
├─ frontend/           # إعدادات الواجهة
└─ adminhtml/          # إعدادات الأدمن
Model/                 # ★ المنطق والبيانات
Block/                 # منطق العرض
Controller/            # ★ معالجة الطلبات
Plugin/                # الـ plugins
Observer/              # مستمعي الأحداث
Setup/Patch/           # تعديل البيانات
Api/                   # ★ الـ interfaces
├─ Data/               # data interfaces
view/                  # ★ الواجهة
├─ frontend/           # templates, layout, js
└─ adminhtml/          # واجهة الأدمن
Ui/                    # UI components
Test/                  # الاختبارات

مفيش موديول بيحتوي كل ده. بتضيف المجلّد لما تحتاجه بس. موديول بسيط ممكن يكون فيه etc/ وModel/ بس.

• • •

مجلّد etc (الأهم)

قلب الإعدادات. كل ملفات الـ XML اللي بتربط الموديول ببعضه.

module.xmlتعريف الموديول واعتمادياته. إجباري.

di.xmlالـ Dependency Injection: preferences، plugins، virtual types. من أكتر ملف هتستخدمه.

events.xmlربط الـ observers بالأحداث. للتفاعل مع أحداث النظام.

db_schema.xmlتعريف جداول قاعدة البيانات (declarative schema).

acl.xmlصلاحيات الأدمن (Access Control List).

crontab.xmlجدولة المهام (cron jobs).

webapi.xmlتعريف الـ REST API endpoints.

ملفات في مجلّدات فرعية

بعض الملفات بتتحط في etc/frontend/ أو etc/adminhtml/ عشان تخص area معيّنة. مثلًا etc/frontend/routes.xml بيعرّف routes الواجهة بس.

القاعدة: ملف في etc/ مباشرة = global (كل الـ areas). ملف في etc/frontend/ = الواجهة بس. ملف في etc/adminhtml/ = الأدمن بس.

• • •

مجلّدات الكود (PHP)

فين بيروح كل نوع كود PHP.

Model/المنطق والبيانات. الـ Models، ResourceModels، Collections.

Controller/معالجة الطلبات (requests). كل action في ملف. للواجهة والأدمن.

Block/منطق العرض — بيجهّز البيانات للـ templates.

Api/الـ interfaces (service contracts) و data interfaces في Api/Data/.

Plugin/الـ plugins اللي بتعدّل سلوك methods (بتتسجّل في di.xml).

Observer/مستمعي الأحداث (بيتسجّلوا في events.xml).

Setup/Patch/Data Patches و Schema Patches لتعديل البيانات عند التثبيت.

Console/أوامر الـ CLI المخصّصة.

Ui/مكوّنات الـ UI للـ grids والـ forms في الأدمن.

لاحظ إن أسماء المجلّدات دي بتطابق الـ namespace. الكلاس في Model/Product.php بيكون namespace بتاعه Vendor\Module\Model. ده اللي اتكلمنا عنه في الـ PSR-4.

• • •

مجلّد view (Frontend)

كل ما يخص الواجهة: templates، layouts، CSS، JS.

view/tree

view/
├─ frontend/
│  ├─ layout/       # XML layouts
│  ├─ templates/    # .phtml files
│  ├─ web/          # css, js, images
│  └─ requirejs-config.js
├─ adminhtml/       # نفس البنية للأدمن
└─ base/            # مشترك بين الاتنين

layout/ملفات XML بتحدد بنية الصفحة وأي blocks تظهر فين.

templates/ملفات .phtml — HTML + PHP للعرض الفعلي.

web/الملفات الثابتة: CSS، JavaScript، الصور، الـ Knockout templates.

خلّي بالك من الفرق: Block/ (في جذر الموديول، PHP) بيجهّز البيانات. view/.../templates/ (phtml) بيعرضها. الاتنين بيشتغلوا مع بعض.

• • •

الـ Areas

مفهوم مهم بيفسّر ليه في مجلّدات frontend و adminhtml في كل مكان.

إيه هي

الـ Area هي سياق تشغيل في Magento. كل area ليها إعداداتها وملفاتها. ده بيسمح إن نفس الموديول يتصرّف بشكل مختلف في الواجهة عن الأدمن.

frontend — واجهة المتجر (اللي العميل بيشوفها).
adminhtml — لوحة تحكّم الأدمن.
global — مشترك بين الكل (ملفات في etc/ مباشرة).
webapi_rest / webapi_soap — سياق الـ APIs.
crontab — سياق المهام المجدولة.

تشبيه الـ areas زي أقسام مختلفة في مطعم: الصالة (frontend) للزباين، المطبخ (adminhtml) للطاقم. نفس المطعم، بس كل قسم ليه قواعده وأدواته. وفيه حاجات مشتركة (global) زي الكهربا.

عشان كده بتلاقي etc/frontend/di.xml وetc/adminhtml/di.xml منفصلين. كل واحد بيطبّق إعدادات على الـ area بتاعته بس. والـ etc/di.xml بيطبّق على الكل.

• • •

التفعيل وأسئلة

إزاي تفعّل الموديول بعد ما تعمله، والأسئلة المتكررة.

terminalbash

# تفعيل الموديول
bin/magento module:enable Vendor_Module

# تطبيق التغييرات (schema, data)
bin/magento setup:upgrade

# إعادة توليد الكود (في production)
bin/magento setup:di:compile

# مسح الـ cache
bin/magento cache:clean

# التأكد إنه اتفعّل
bin/magento module:status Vendor_Module

الترتيب المعتاد بعد إضافة موديول: module:enable → setup:upgrade → cache:clean. لو ضفت DI، ضيف di:compile.

Q1إيه أقل ملفات لموديول شغّال؟

الإجابة: ملفين بس — registration.php وetc/module.xml. دول بيخلّوا الموديول "موجود ومسجّل"، وبعدها تضيف اللي محتاجه.

Q2الفرق بين app/code و vendor؟

الإجابة: app/code/ للموديولات بتاعتك (custom). vendor/ للموديولات المثبّتة عن طريق Composer (Magento core والحزم الخارجية). متعدّلش الـ vendor.

Q3ليه في مجلّدات frontend و adminhtml مكرّرة؟

الإجابة: بسبب الـ areas. كل area ليها سياقها، فالإعدادات والملفات بتتفصل عشان الموديول يتصرّف مختلف في الواجهة عن الأدمن.

Q4ضفت موديول ومش ظاهر، إيه الأسباب؟

الإجابة: غالبًا نسيت setup:upgrade أو cache:clean، أو خطأ في اسم الموديول بين registration و module.xml، أو الـ namespace مش مطابق للمسار.

هيكل الموديول ✓

دلوقتي عندك خريطة كاملة للموديول: الملفان الإجباريان، مجلّد etc، مجلّدات الكود، الـ view، والـ areas. مش مطلوب تحفظ — مطلوب تفهم إن كل نوع ملف ليه مكان منطقي.

الخلاصة: كل حاجة معزولة في module، وكل نوع ملف ليه مكانه، والـ areas بتفصل السياقات. بمجرد ما تألف البنية دي، أي موديول تفتحه هيبقى مفهوم — وده أساس كل اللي جاي.

// magento 2 · module structure · beginner

خلّصت الدرس؟علّمه عشان تتابع تقدّمك في الكورس.

كاتب الدرس

Abdulrahman Masoud

عندك سؤال على الدرس أو محتاج مساعدة في مشروع Magento؟ كلّمني.

وظّفني

أسئلة شائعة

إيه أقل ملفات محتاجها عشان أعمل module في Magento 2؟

ملفين بس: registration.php اللي بيسجّل الموديول بـ ComponentRegistrar::register() باسمه الرسمي زي Vendor_Module، وetc/module.xml اللي بيعرّف اسمه والـ sequence بتاعه. بتحطهم في app/code/Vendor/Module/، وأي مجلّد تاني بتضيفه لما تحتاجه.

ما الفرق بين app/code و vendor في Magento 2؟

app/code/ مكان الموديولات بتاعتك (custom)، وvendor/ فيه الموديولات اللي اتثبّتت عن طريق Composer زي Magento core والحزم الخارجية. متعدّلش حاجة في vendor/ أبدًا، ولو عايز تغيّر سلوك موديول core استخدم plugins أو events من موديولك.

إزاي أفعّل module جديد في Magento 2؟

الترتيب المعتاد: bin/magento module:enable Vendor_Module وبعده bin/magento setup:upgrade وبعده bin/magento cache:clean. لو ضفت إعدادات DI أو شغّال production شغّل setup:di:compile، واتأكد إن الموديول اتفعّل بـ bin/magento module:status Vendor_Module.

يعني إيه Area في Magento 2؟

الـ Area سياق تشغيل ليه إعداداته وملفاته: frontend لواجهة المتجر، وadminhtml للوحة التحكم، وwebapi_rest وwebapi_soap للـ APIs، وcrontab للمهام المجدولة، وglobal للمشترك. عشان كده etc/di.xml بيتطبّق على الكل، وetc/frontend/di.xml على الواجهة بس.

إيه أهم ملفات مجلد etc في Magento 2 module؟

أهمهم module.xml (إجباري) وdi.xml للـ preferences والـ plugins والـ virtual types، وevents.xml لربط الـ observers، وdb_schema.xml لتعريف الجداول بالـ declarative schema. وفيه كمان acl.xml للصلاحيات، وcrontab.xml للـ cron jobs، وwebapi.xml لتعريف الـ REST endpoints.

ليه الموديول بتاعي مش ظاهر في Magento 2؟

غالبًا نسيت تشغّل setup:upgrade أو cache:clean بعد ما فعّلته. ومن الأسباب كمان اختلاف اسم الموديول بين registration.php وmodule.xml، أو إن الـ namespace مش مطابق لمسار الملف.

ما الفرق بين مجلد Block و templates في Magento 2؟

مجلّد Block/ في جذر الموديول فيه كلاسات PHP بتجهّز البيانات للعرض. أما view/frontend/templates/ فيه ملفات .phtml (HTML + PHP) اللي بتعرضها فعليًا، وملفات الـ layout/ XML بتحدد أنهي blocks تظهر فين في الصفحة.

يعني إيه Module؟

الملفان الإجباريان

الهيكل الكامل

مجلّد etc (الأهم)

مجلّدات الكود (PHP)

مجلّد view (Frontend)

الـ Areas

التفعيل وأسئلة

هيكل الموديول ✓

أسئلة شائعة

دروس مرتبطة