1.02

Describe Module Structure

Understanding the essential architecture and requirements of a Magento module.

Why This Matters: Modules are self-contained units of functionality where customizations are typically located. Each module performs a specific set of updates or adds new functionality.

Module Structure Overview

mindmap root((Module Structure)) Location app/code/Vendor/Module vendor/ via Composer Identity Module Name Vendor_Module PSR-4 Path Vendor\\Module Required Files registration.php Register module Required composer.json Dependencies Autoload PSR-4 type magento2-module etc/module.xml Module name Dependencies sequence Installation bin/magento module:enable bin/magento setup:upgrade --keep-generated flag

Module Location and Naming

A Magento 2 module is generally found in the app/code/VendorName/ModuleName directory.

Directory Structure

  • Custom modules: app/code/VendorName/ModuleName
  • Third-party modules: vendor/ (installed via Composer)
Best Practice: Third-party modules should be installed via Composer into the vendor/ directory, not app/code.

Module Identity

A module's identity involves two parts:

1️⃣ Module Name

The name Magento uses to recognize and identify the module.

Bonlineco_Blog

Format: VendorName_ModuleName

2️⃣ PSR-4 Path

The namespace path used in code, used by Composer to autoload files.

Bonlineco\Blog

Format: VendorName\ModuleName

When to Create a New Module

You should create a new module in these scenarios:

Create a New Module When:
  • Adding new features with significant code (estimated >250 lines)
  • Customizing functionality in a different existing Magento module
  • Creating a supporting framework for a new child theme (e.g., MerchantName/Theme)
    • Contains ViewModels, LESS, and Layout XML
  • Grouping general customizations by area of functionality (e.g., MerchantName/Catalog)
  • Modifying a third-party module (e.g., MerchantName/VendorModuleName)

Required Module Files

A custom module requires several mandatory files in its directory:

1. registration.php

registration.php
⚠️ Mandatory - This file is essential for registering the module.

Purpose:

  • Used by Composer to determine which files to autoload based on namespace path
  • Used by Magento to understand which modules are available in the system

Example:

<?php
use Magento\Framework\Component\ComponentRegistrar;

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

2. composer.json

composer.json
Recommended: Although a module may temporarily work without this file, it is always recommended.

Purpose:

  • Primarily used by Composer to define requirements and paths
  • Must specify type as "magento2-module"
  • The autoload section specifies PSR-4 path mapping

Example:

{
    "name": "bonlineco/module-blog",
    "description": "Blog module for Bonlineco store",
    "type": "magento2-module",
    "version": "1.0.0",
    "require": {
        "php": "~8.1.0||~8.2.0",
        "magento/framework": "*"
    },
    "autoload": {
        "psr-4": {
            "Bonlineco\\\\Blog\\\\": ""
        },
        "files": [
            "registration.php"
        ]
    }
}
Key Points:
  • "type": "magento2-module" identifies this as a Magento module
  • PSR-4 mapping: "Bonlineco\\\\Blog\\\\": "" maps to current directory
  • Files array includes registration.php for autoloading

3. etc/module.xml

etc/module.xml
⚠️ Mandatory - Specifies the module's name and manages dependencies.

Purpose:

  • Must specify the module's name, matching the name in registration.php
  • The <sequence> element defines modules this module depends on
  • If a module is in the sequence, Magento won't allow it to be disabled if this module is enabled

Example:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Bonlineco_Blog" setup_version="1.0.0">
        <sequence>
            <module name="Magento_Cms"/>
            <module name="Magento_Customer"/>
        </sequence>
    </module>
</config>
Dependency Management:
  • If Magento_Cms is listed in sequence, it cannot be disabled while Bonlineco_Blog is enabled
  • This ensures all required modules are active
  • The sequence also controls the order in which modules load

Steps to Add a New Module

After creating the directory and populating the mandatory files, perform these command-line actions:

Installation Steps

Step 1: Enable the Module

bin/magento module:enable Bonlineco_Blog

Step 2: Install/Synchronize

bin/magento setup:upgrade

What setup:upgrade does:

  • Synchronizes the database schema
  • Runs any necessary setup scripts
  • Installs the module into the database (visible in setup_module table)
Optional Flag: --keep-generated 
bin/magento setup:upgrade --keep-generated

Purpose:

  • Prevents deletion of the generated/ directory
  • Speeds up the development process
  • ⚠️ Do NOT use if your module modifies:
    • Extension attributes
    • Plugins
  • If unsure, manually delete generated/ directory to ensure changes take effect

Module Directory Structure Example

Complete Module Structure

app/code/Bonlineco/Blog/
├── registration.php         (Required)
├── composer.json           (Recommended)
├── etc/
│   ├── module.xml         (Required)
│   ├── di.xml
│   └── acl.xml
├── Block/
├── Controller/
├── Model/
├── Setup/
├── view/
│   ├── frontend/
│   └── adminhtml/
└── i18n/

Quick Reference

File Required? Purpose
registration.php Required Registers module with Magento and Composer
composer.json Recommended Defines dependencies and PSR-4 autoloading
etc/module.xml Required Module name and dependency sequence

Exam Tips

Key Points to Remember

  • Know the difference between Module Name (Vendor_Module) and PSR-4 Path (Vendor\Module)
  • Understand the 3 required files and their purposes
  • Remember that <sequence> in module.xml controls dependencies and load order
  • Know when to use --keep-generated flag (and when NOT to use it)
  • Understand the criteria for creating a new module (>250 lines, customizing other modules, etc.)
  • Remember that composer.json must have "type": "magento2-module"
  • Know the two-step process: module:enable then setup:upgrade
Previous: 1.01 File Structure Next: 1.03 di.xml Usage